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

swbt/__init__.py

@@ -15,8 +15,13 @@ from swbt.errors import (
 )
 from swbt.gamepad import (
     ConnectionResult,
+    DirectJoyConL,
+    DirectJoyConR,
+    DirectProController,
+    DirectSwitchGamepad,
     JoyConL,
     JoyConR,
+    PeriodicSwitchGamepad,
     ProController,
     SwitchGamepad,
 )
@@ -33,6 +38,10 @@ __all__ = (
     "ConnectionTimeoutError",
     "ControllerColors",
     "DiagnosticsConfig",
+    "DirectJoyConL",
+    "DirectJoyConR",
+    "DirectProController",
+    "DirectSwitchGamepad",
     "GamepadStatus",
     "IMUFrame",
     "InputState",
@@ -40,6 +49,7 @@ __all__ = (
     "InvalidKeyStoreError",
     "JoyConL",
     "JoyConR",
+    "PeriodicSwitchGamepad",
     "ProController",
     "Stick",
     "SwbtError",

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
@@ -72,3 +81,65 @@ def make_joycon_r(
         diagnostics=diagnostics,
         transport=transport,
     )
+
+
+def make_direct_pro_controller(
+    *,
+    transport: HidDeviceTransport,
+    adapter: str | None = None,
+    key_store_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,
+            key_store_path=key_store_path,
+            controller_colors=controller_colors,
+        ),
+        diagnostics=diagnostics,
+        transport=transport,
+    )
+
+
+def make_direct_joycon_l(
+    *,
+    transport: HidDeviceTransport,
+    adapter: str | None = None,
+    key_store_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,
+            key_store_path=key_store_path,
+            controller_colors=controller_colors,
+            profile=JoyConLeftProfile(),
+        ),
+        diagnostics=diagnostics,
+        transport=transport,
+    )
+
+
+def make_direct_joycon_r(
+    *,
+    transport: HidDeviceTransport,
+    adapter: str | None = None,
+    key_store_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,
+            key_store_path=key_store_path,
+            controller_colors=controller_colors,
+            profile=JoyConRightProfile(),
+        ),
+        diagnostics=diagnostics,
+        transport=transport,
+    )

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/core.py

@@ -1,12 +1,15 @@
 """Public gamepad API."""
 
-from typing import Self
+from typing import ClassVar, Literal, Self
 
 from swbt.diagnostics import DiagnosticsConfig, GamepadStatus
 from swbt.errors import InvalidInputError
 from swbt.gamepad._config import _ControllerSpec, _SwitchGamepadConfig
 from swbt.gamepad.connection import ConnectionResult
-from swbt.gamepad.interface import SwitchGamepad
+from swbt.gamepad.interface import (
+    DirectSwitchGamepad,
+    PeriodicSwitchGamepad,
+)
 from swbt.gamepad.output import OutputReportDispatcher
 from swbt.gamepad.runtime import ControllerRuntime
 from swbt.input import Button, IMUFrame, InputState, Stick
@@ -17,7 +20,7 @@ from swbt.state_store import InputStateStore
 from swbt.transport.base import HidDeviceTransport
 
 
-class _RuntimeBackedGamepad(SwitchGamepad):
+class _RuntimeBackedGamepad:
     """Runtime-backed concrete gamepad base.
 
     The object owns the public API surface and delegates stateful
@@ -25,6 +28,7 @@ class _RuntimeBackedGamepad(SwitchGamepad):
     """
 
     _controller_spec = _ControllerSpec(profile=default_controller_profile())
+    _reporting_mode: ClassVar[Literal["periodic", "direct"]] = "periodic"
 
     def __init__(
         self,
@@ -65,6 +69,7 @@ class _RuntimeBackedGamepad(SwitchGamepad):
         self._runtime = ControllerRuntime.from_config(
             config,
             diagnostics=diagnostics,
+            reporting_mode=self._reporting_mode,
             transport=transport,
         )
 
@@ -113,8 +118,9 @@ class _RuntimeBackedGamepad(SwitchGamepad):
     async def open(self) -> None:
         """Open the configured transport.
 
-        Opening prepares transport callbacks, diagnostics metadata, and the report
-        loop. It does not start HID advertising, pairing, or active reconnect.
+        Opening prepares transport callbacks, diagnostics metadata, and the
+        reporting-type resources. It does not start HID advertising, pairing,
+        or active reconnect.
 
         Raises:
             TransportOpenError: Raised by the transport when the adapter cannot be opened.
@@ -218,22 +224,13 @@ class _RuntimeBackedGamepad(SwitchGamepad):
         Args:
             buttons: Buttons to add to the current button set.
 
-        This updates local state only and does not send an immediate input report.
+        A periodic controller commits local state. A direct controller sends one
+        input report and commits only after transmission succeeds.
         """
         await self._runtime.press(*buttons)
 
-    async def apply(self, state: InputState) -> None:
-        """Replace the current input state without immediate transmission.
-
-        Args:
-            state: Complete input state to commit.
-
-        This updates local state only and does not send an immediate input report.
-        """
-        await self._runtime.apply(state)
-
     async def sticks(self, *, left: Stick | None = None, right: Stick | None = None) -> None:
-        """Replace one or both stick positions without immediate transmission.
+        """Replace one or both stick positions according to the reporting type.
 
         Args:
             left: Optional replacement for the left stick.
@@ -242,12 +239,13 @@ class _RuntimeBackedGamepad(SwitchGamepad):
         Raises:
             InvalidInputError: ``left`` or ``right`` is not a ``Stick``.
 
-        This updates local state only and does not send an immediate input report.
+        A periodic controller commits local state. A direct controller sends one
+        input report and commits only after transmission succeeds.
         """
         await self._runtime.sticks(left=left, right=right)
 
     async def lstick(self, stick: Stick) -> None:
-        """Replace the left stick position without immediate transmission.
+        """Replace the left stick position according to the reporting type.
 
         Args:
             stick: Replacement for the left stick.
@@ -255,12 +253,13 @@ class _RuntimeBackedGamepad(SwitchGamepad):
         Raises:
             InvalidInputError: ``stick`` is not a ``Stick``.
 
-        This updates local state only and does not send an immediate input report.
+        A periodic controller commits local state. A direct controller sends one
+        input report and commits only after transmission succeeds.
         """
         await self._runtime.lstick(stick)
 
     async def rstick(self, stick: Stick) -> None:
-        """Replace the right stick position without immediate transmission.
+        """Replace the right stick position according to the reporting type.
 
         Args:
             stick: Replacement for the right stick.
@@ -268,12 +267,13 @@ class _RuntimeBackedGamepad(SwitchGamepad):
         Raises:
             InvalidInputError: ``stick`` is not a ``Stick``.
 
-        This updates local state only and does not send an immediate input report.
+        A periodic controller commits local state. A direct controller sends one
+        input report and commits only after transmission succeeds.
         """
         await self._runtime.rstick(stick)
 
     async def imu(self, *frames: IMUFrame) -> None:
-        """Replace IMU frames without immediate transmission.
+        """Replace IMU frames according to the reporting type.
 
         Args:
             frames: One ``IMUFrame`` to repeat across all three IMU slots, or exactly
@@ -293,12 +293,13 @@ class _RuntimeBackedGamepad(SwitchGamepad):
         Args:
             buttons: Buttons to remove from the current button set.
 
-        This updates local state only and does not send an immediate input report.
+        A periodic controller commits local state. A direct controller sends one
+        input report and commits only after transmission succeeds.
         """
         await self._runtime.release(*buttons)
 
     async def neutral(self) -> None:
-        """Return local input state to ``InputState.neutral()`` without immediate transmission."""
+        """Apply ``InputState.neutral()`` according to the reporting type."""
         await self._runtime.neutral()
 
     async def tap(self, *buttons: Button, duration: float = 0.08) -> None:
@@ -327,19 +328,77 @@ class _RuntimeBackedGamepad(SwitchGamepad):
     def snapshot(self) -> InputState:
         """Return the latest committed input state.
 
+        A periodic controller returns its latest local state. A direct
+        controller returns the last state sent successfully.
+
         Returns:
             InputState: Immutable snapshot of the current input state.
         """
         return self._runtime.snapshot()
 
 
-class ProController(_RuntimeBackedGamepad):
+class _PeriodicRuntimeBackedGamepad(_RuntimeBackedGamepad, PeriodicSwitchGamepad):
+    """Runtime-backed gamepad with library-owned periodic input transmission."""
+
+    async def apply(self, state: InputState) -> None:
+        """Replace the current input state without immediate transmission.
+
+        Args:
+            state: Complete input state to commit.
+
+        This updates local state only and does not send an immediate input report.
+        """
+        await self._runtime.apply(state)
+
+
+class _DirectRuntimeBackedGamepad(_RuntimeBackedGamepad, DirectSwitchGamepad):
+    """Runtime-backed gamepad with caller-owned input transmission."""
+
+    _reporting_mode = "direct"
+
+    def __init__(
+        self,
+        *,
+        adapter: str | None = None,
+        key_store_path: str | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> None:
+        """Create a direct-reporting gamepad object.
+
+        Args:
+            adapter: Bumble adapter moniker used for the Bluetooth backend.
+            key_store_path: Optional path used by the Bluetooth backend to persist keys.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Raises:
+            InvalidInputError: ``adapter`` is omitted.
+        """
+        config = self._controller_spec.build_config(
+            adapter=adapter,
+            key_store_path=key_store_path,
+            report_period_us=None,
+            controller_colors=controller_colors,
+        )
+        self._init_from_config(config, diagnostics=diagnostics, transport=None)
+
+    async def send(self, state: InputState) -> None:
+        """Send one complete input state and commit it after transmission.
+
+        Args:
+            state: Complete input state to send.
+        """
+        await self._runtime.send(state)
+
+
+class ProController(_PeriodicRuntimeBackedGamepad):
     """Runtime-backed Pro Controller-compatible gamepad."""
 
     _controller_spec = _ControllerSpec(profile=default_controller_profile())
 
 
-class JoyConL(_RuntimeBackedGamepad):
+class JoyConL(_PeriodicRuntimeBackedGamepad):
     """Runtime-backed Joy-Con L-compatible gamepad."""
 
     _controller_spec = _ControllerSpec(profile=JoyConLeftProfile())
@@ -374,7 +433,7 @@ class JoyConL(_RuntimeBackedGamepad):
         self._init_from_config(config, diagnostics=diagnostics, transport=None)
 
 
-class JoyConR(_RuntimeBackedGamepad):
+class JoyConR(_PeriodicRuntimeBackedGamepad):
     """Runtime-backed Joy-Con R-compatible gamepad."""
 
     _controller_spec = _ControllerSpec(profile=JoyConRightProfile())
@@ -407,3 +466,21 @@ class JoyConR(_RuntimeBackedGamepad):
             controller_colors=controller_colors,
         )
         self._init_from_config(config, diagnostics=diagnostics, transport=None)
+
+
+class DirectProController(_DirectRuntimeBackedGamepad):
+    """Direct-reporting Pro Controller-compatible gamepad."""
+
+    _controller_spec = _ControllerSpec(profile=default_controller_profile())
+
+
+class DirectJoyConL(_DirectRuntimeBackedGamepad):
+    """Direct-reporting Joy-Con L-compatible gamepad."""
+
+    _controller_spec = _ControllerSpec(profile=JoyConLeftProfile())
+
+
+class DirectJoyConR(_DirectRuntimeBackedGamepad):
+    """Direct-reporting Joy-Con R-compatible gamepad."""
+
+    _controller_spec = _ControllerSpec(profile=JoyConRightProfile())

swbt/gamepad/interface.py

@@ -2,6 +2,7 @@
 
 from abc import ABC, abstractmethod
 from types import TracebackType
+from typing import Self
 
 from swbt.diagnostics import GamepadStatus
 from swbt.gamepad.connection import ConnectionResult
@@ -9,14 +10,15 @@ from swbt.input import Button, IMUFrame, InputState, Stick
 
 
 class SwitchGamepad(ABC):
-    """Shared public interface for NX-compatible virtual gamepads.
+    """Shared abstract public interface for NX-compatible virtual gamepads.
 
-    Use this abstract base class for type annotations. Construct
-    ``ProController``, ``JoyConL``, or ``JoyConR`` for a concrete virtual
-    controller.
+    Use ``PeriodicSwitchGamepad`` or ``DirectSwitchGamepad`` when a type
+    annotation must express who owns the input-report schedule. Common input
+    operations commit local state on periodic gamepads; on direct gamepads they
+    send one input report and commit only after transmission succeeds.
     """
 
-    async def __aenter__(self) -> "SwitchGamepad":
+    async def __aenter__(self) -> Self:
         """Open the gamepad for an async context manager.
 
         Returns:
@@ -45,8 +47,9 @@ class SwitchGamepad(ABC):
     async def open(self) -> None:
         """Open the configured transport.
 
-        Opening prepares transport callbacks, diagnostics metadata, and the report
-        loop. It does not start HID advertising, pairing, or active reconnect.
+        Opening prepares transport callbacks, diagnostics metadata, and the
+        reporting-type resources. It does not start HID advertising, pairing,
+        or active reconnect.
 
         Raises:
             TransportOpenError: The configured transport cannot be opened.
@@ -160,25 +163,13 @@ class SwitchGamepad(ABC):
             InvalidInputError: Any value is not a ``Button``.
             UnsupportedInputError: The controller profile does not support a button.
 
-        This updates local state only and does not send an immediate input report.
-        """
-
-    @abstractmethod
-    async def apply(self, state: InputState) -> None:
-        """Replace the current input state without immediate transmission.
-
-        Args:
-            state: Complete input state to commit.
-
-        Raises:
-            InvalidInputError: ``state`` is not an ``InputState``.
-            UnsupportedInputError: The controller profile does not support part of
-                the supplied state.
+        Completion follows the reporting type: periodic gamepads commit local
+        state, while direct gamepads send one input report and then commit.
         """
 
     @abstractmethod
     async def sticks(self, *, left: Stick | None = None, right: Stick | None = None) -> None:
-        """Replace one or both stick positions without immediate transmission.
+        """Replace one or both stick positions according to the reporting type.
 
         Args:
             left: Optional replacement for the left stick.
@@ -191,7 +182,7 @@ class SwitchGamepad(ABC):
 
     @abstractmethod
     async def lstick(self, stick: Stick) -> None:
-        """Replace the left stick position without immediate transmission.
+        """Replace the left stick position according to the reporting type.
 
         Args:
             stick: Replacement for the left stick.
@@ -203,7 +194,7 @@ class SwitchGamepad(ABC):
 
     @abstractmethod
     async def rstick(self, stick: Stick) -> None:
-        """Replace the right stick position without immediate transmission.
+        """Replace the right stick position according to the reporting type.
 
         Args:
             stick: Replacement for the right stick.
@@ -215,7 +206,7 @@ class SwitchGamepad(ABC):
 
     @abstractmethod
     async def imu(self, *frames: IMUFrame) -> None:
-        """Replace IMU frames without immediate transmission.
+        """Replace IMU frames according to the reporting type.
 
         Args:
             frames: One ``IMUFrame`` to repeat across all three IMU slots, or exactly
@@ -240,7 +231,7 @@ class SwitchGamepad(ABC):
 
     @abstractmethod
     async def neutral(self) -> None:
-        """Return local input state to ``InputState.neutral()`` without immediate transmission."""
+        """Apply ``InputState.neutral()`` according to the reporting type."""
 
     @abstractmethod
     async def tap(self, *buttons: Button, duration: float = 0.08) -> None:
@@ -268,6 +259,44 @@ class SwitchGamepad(ABC):
     def snapshot(self) -> InputState:
         """Return the latest committed input state.
 
+        A periodic gamepad returns its latest local state. A direct gamepad
+        returns the last state whose input report was sent successfully.
+
         Returns:
             InputState: Immutable snapshot of the current input state.
         """
+
+
+class PeriodicSwitchGamepad(SwitchGamepad):
+    """Abstract gamepad whose input report schedule is owned by the library."""
+
+    @abstractmethod
+    async def apply(self, state: InputState) -> None:
+        """Replace the current local input state without immediate transmission.
+
+        Args:
+            state: Complete input state to commit.
+
+        Raises:
+            InvalidInputError: ``state`` is not an ``InputState``.
+            UnsupportedInputError: The controller profile does not support part of
+                the supplied state.
+        """
+
+
+class DirectSwitchGamepad(SwitchGamepad):
+    """Abstract gamepad whose input report schedule is owned by the caller."""
+
+    @abstractmethod
+    async def send(self, state: InputState) -> None:
+        """Send one complete input state and commit it after transmission.
+
+        Args:
+            state: Complete input state to send.
+
+        Raises:
+            ClosedError: The gamepad is not connected.
+            InvalidInputError: ``state`` is not an ``InputState``.
+            UnsupportedInputError: The controller profile does not support part of
+                the supplied state.
+        """

swbt/gamepad/output.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass, field
 
 from swbt.diagnostics import DiagnosticsRecorder
 from swbt.protocol.output_report import OutputReportParser
+from swbt.protocol.session import SwitchHidSession
 from swbt.protocol.subcommand import (
     SESSION_STATE_SUBCOMMANDS,
     SubcommandResponder,
@@ -12,7 +13,8 @@ from swbt.protocol.subcommand import (
 )
 from swbt.state_store import InputStateStore
 
-ReplySender = Callable[[bytes], Awaitable[None]]
+ReplyBuilder = Callable[[], bytes | Awaitable[bytes]]
+ReplySender = Callable[[ReplyBuilder], Awaitable[bytes]]
 ReplySenderRequirement = Callable[[], None]
 
 
@@ -23,6 +25,7 @@ class OutputReportDispatcher:
     diagnostics: DiagnosticsRecorder
     require_reply_sender: ReplySenderRequirement
     send_subcommand_reply: ReplySender
+    session: SwitchHidSession
     state_store: InputStateStore
     output_report_parser: OutputReportParser = field(default_factory=OutputReportParser)
     subcommand_responder: SubcommandResponder = field(default_factory=SubcommandResponder)
@@ -47,9 +50,17 @@ class OutputReportDispatcher:
             subcommand_id=output_report.subcommand_id,
         )
         self.require_reply_sender()
-        state = await self.state_store.snapshot()
         try:
-            reply = self.subcommand_responder.respond(output_report, state=state)
+
+            async def build_reply() -> bytes:
+                state = await self.state_store.snapshot()
+                return self.subcommand_responder.respond(
+                    output_report,
+                    state=state,
+                    session=self.session,
+                )
+
+            reply = await self.send_subcommand_reply(build_reply)
         except UnsupportedSubcommandError:
             self.diagnostics.record_event(
                 "unsupported_subcommand",
@@ -59,10 +70,11 @@ class OutputReportDispatcher:
             )
             raise
         if output_report.subcommand_id in SESSION_STATE_SUBCOMMANDS:
-            session_state = self.subcommand_responder.session_state
+            session_state = self.session.state
             self.diagnostics.record_event(
                 "subcommand_session_state",
                 imu_enabled=session_state.imu_enabled,
+                imu_encoding_format=session_state.imu_encoding_format,
                 imu_mode=_format_optional_byte(session_state.imu_mode),
                 packet_id=output_report.packet_id,
                 report_mode=_format_optional_byte(session_state.report_mode),
@@ -79,7 +91,6 @@ class OutputReportDispatcher:
             report_id=_format_report_id(reply[0]),
             subcommand_id=subcommand_id,
         )
-        await self.send_subcommand_reply(reply)
 
 
 def _format_report_id(report_id: int) -> str: