swbt-python 0.3.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

@@ -13,7 +13,7 @@ from swbt.protocol.subcommand import (
 )
 from swbt.state_store import InputStateStore
 
-ReplyBuilder = Callable[[], bytes]
+ReplyBuilder = Callable[[], bytes | Awaitable[bytes]]
 ReplySender = Callable[[ReplyBuilder], Awaitable[bytes]]
 ReplySenderRequirement = Callable[[], None]
 
@@ -50,15 +50,17 @@ class OutputReportDispatcher:
             subcommand_id=output_report.subcommand_id,
         )
         self.require_reply_sender()
-        state = await self.state_store.snapshot()
         try:
-            reply = await self.send_subcommand_reply(
-                lambda: self.subcommand_responder.respond(
+
+            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",

swbt/gamepad/runtime.py

@@ -1,9 +1,10 @@
 """Stateful runtime for gamepad lifecycle and input behavior."""
 
 import asyncio
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from dataclasses import replace
 from types import TracebackType
+from typing import Literal
 
 import swbt.gamepad as gamepad_module
 from swbt.diagnostics import DiagnosticsConfig, DiagnosticsRecorder, GamepadStatus
@@ -29,7 +30,7 @@ from swbt.protocol.input_report import InputReportBuilder
 from swbt.protocol.profiles.base import ControllerColors
 from swbt.protocol.session import SwitchHidSession
 from swbt.protocol.subcommand import SubcommandResponder
-from swbt.report_loop import ReportLoop
+from swbt.report_loop import ReportLoop, ReportSender
 from swbt.state_store import InputStateStore
 from swbt.transport.base import DisconnectRequestResult, HidDeviceTransport
 
@@ -83,6 +84,7 @@ class ControllerRuntime:
         config: _SwitchGamepadConfig,
         *,
         diagnostics: DiagnosticsConfig | None,
+        reporting_mode: Literal["periodic", "direct"] = "periodic",
         transport: HidDeviceTransport | None,
     ) -> None:
         runtime_config = _RuntimeConfig.from_public_config(config)
@@ -90,6 +92,7 @@ class ControllerRuntime:
             msg = "adapter is required when no custom transport is supplied"
             raise InvalidInputError(msg)
         self._config = runtime_config
+        self._reporting_mode = reporting_mode
         self._transport = transport
         self._transport_was_injected = transport is not None
         if transport is None:
@@ -117,6 +120,8 @@ class ControllerRuntime:
             ),
         )
         self._report_loop: ReportLoop | None = None
+        self._report_sender: ReportSender | None = None
+        self._input_operation_lock = asyncio.Lock()
         self._lifecycle_lock = asyncio.Lock()
         self._connected_event = asyncio.Event()
         self._disconnect_event = asyncio.Event()
@@ -143,6 +148,7 @@ class ControllerRuntime:
         config: _SwitchGamepadConfig,
         *,
         diagnostics: DiagnosticsConfig | None = None,
+        reporting_mode: Literal["periodic", "direct"] = "periodic",
         transport: HidDeviceTransport | None = None,
     ) -> "ControllerRuntime":
         """Create a runtime from an explicit resource configuration.
@@ -150,6 +156,7 @@ class ControllerRuntime:
         Args:
             config: Resource configuration for the runtime.
             diagnostics: Optional diagnostics configuration for trace output.
+            reporting_mode: Internal owner of normal input report scheduling.
             transport: Optional HID transport instance.
 
         Returns:
@@ -159,6 +166,7 @@ class ControllerRuntime:
         runtime._init_from_config(
             config,
             diagnostics=diagnostics,
+            reporting_mode=reporting_mode,
             transport=transport,
         )
         return runtime
@@ -210,22 +218,36 @@ class ControllerRuntime:
             try:
                 await transport.open()
                 self._configure_device_info_bluetooth_address(transport)
-                self._report_loop = ReportLoop(
+                report_sender = ReportSender(
                     transport=transport,
-                    state_store=self._state_store,
-                    report_period_us=self._config.report_period_us,
                     input_report_builder=InputReportBuilder(
                         self._controller_profile,
                     ),
                     session=self._protocol_session,
                     diagnostics=self._diagnostics,
                 )
+                self._report_sender = report_sender
+                if self._reporting_mode == "periodic":
+                    self._report_loop = ReportLoop(
+                        transport=transport,
+                        state_store=self._state_store,
+                        report_period_us=self._config.report_period_us,
+                        input_report_builder=InputReportBuilder(
+                            self._controller_profile,
+                        ),
+                        session=self._protocol_session,
+                        diagnostics=self._diagnostics,
+                        sender=report_sender,
+                    )
+                else:
+                    self._report_loop = None
                 self._connection_state = "opened"
                 self._is_open = True
             except Exception:
                 self._connection_state = "failed"
                 await transport.close()
                 self._report_loop = None
+                self._report_sender = None
                 self._is_open = False
                 raise
 
@@ -393,6 +415,7 @@ class ControllerRuntime:
                         )
                 await self._transport.close()
                 self._report_loop = None
+                self._report_sender = None
                 self._is_open = False
                 self._connection_state = "closed"
             finally:
@@ -406,8 +429,15 @@ class ControllerRuntime:
 
         This updates local state only and does not send an immediate input report.
         """
+
+        def transform(current: InputState) -> InputState:
+            return current.with_buttons((*current.buttons, *buttons))
+
+        if self._reporting_mode == "direct":
+            await self._send_direct_update(transform)
+            return
         await self._state_store.update(
-            lambda current: current.with_buttons((*current.buttons, *buttons)),
+            transform,
             validate=self._controller_profile.validate_input_state,
         )
 
@@ -422,6 +452,14 @@ class ControllerRuntime:
         self._controller_profile.validate_input_state(state)
         await self._state_store.apply(state)
 
+    async def send(self, state: InputState) -> None:
+        """Send one complete state through a direct-reporting runtime."""
+        if self._reporting_mode != "direct":
+            msg = "send is only available for direct reporting"
+            raise InvalidInputError(msg)
+        self._validate_input_state(state)
+        await self._send_direct_update(lambda _current: state)
+
     async def sticks(self, *, left: Stick | None = None, right: Stick | None = None) -> None:
         """Replace one or both stick positions without immediate transmission.
 
@@ -440,8 +478,15 @@ class ControllerRuntime:
             left=left is not None,
             right=right is not None,
         )
+
+        def transform(current: InputState) -> InputState:
+            return current.with_sticks(left_stick=left, right_stick=right)
+
+        if self._reporting_mode == "direct":
+            await self._send_direct_update(transform)
+            return
         await self._state_store.update(
-            lambda current: current.with_sticks(left_stick=left, right_stick=right),
+            transform,
             validate=self._controller_profile.validate_input_state,
         )
 
@@ -484,6 +529,9 @@ class ControllerRuntime:
 
         This updates local IMU state only and does not send an immediate input report.
         """
+        if self._reporting_mode == "direct":
+            await self._send_direct_update(lambda current: current.with_imu(*frames))
+            return
         await self._state_store.imu(*frames)
 
     async def release(self, *buttons: Button) -> None:
@@ -495,13 +543,23 @@ class ControllerRuntime:
         This updates local state only and does not send an immediate input report.
         """
         self._controller_profile.validate_buttons(buttons)
+
+        def transform(current: InputState) -> InputState:
+            return current.with_buttons(current.buttons.difference(buttons))
+
+        if self._reporting_mode == "direct":
+            await self._send_direct_update(transform)
+            return
         await self._state_store.update(
-            lambda current: current.with_buttons(current.buttons.difference(buttons)),
+            transform,
             validate=self._controller_profile.validate_input_state,
         )
 
     async def neutral(self) -> None:
         """Return local input state to ``InputState.neutral()`` without immediate transmission."""
+        if self._reporting_mode == "direct":
+            await self._send_direct_update(lambda _current: InputState.neutral())
+            return
         await self._state_store.neutral()
 
     async def tap(self, *buttons: Button, duration: float = 0.08) -> None:
@@ -517,6 +575,9 @@ class ControllerRuntime:
         The tap sends immediate press and release input reports. The release step
         removes only the buttons supplied to this call, preserving other held buttons.
         """
+        if self._reporting_mode == "direct":
+            await self._tap_direct(*buttons, duration=duration)
+            return
         self._require_connected_for_input()
         await self.press(*buttons)
         primary_error: BaseException | None = None
@@ -588,34 +649,94 @@ class ControllerRuntime:
         )
 
     async def _send_trailing_neutral_if_connected(self) -> None:
+        if self._reporting_mode == "direct":
+            async with self._input_operation_lock:
+                if self._report_sender is None or not self._connected_event.is_set():
+                    return
+                await self._send_direct_candidate(InputState.neutral())
+            return
         await self._state_store.neutral()
         if self._report_loop is None or not self._connected_event.is_set():
             return
         await self._report_loop.send_current_input()
 
     async def _send_current_input(self) -> None:
-        if self._report_loop is None:
-            msg = "gamepad is not open"
-            raise ClosedError(msg)
-        await self._report_loop.send_current_input()
+        state = await self._state_store.snapshot()
+        await self._require_report_sender().send_input(state)
 
     def _require_subcommand_reply_sender(self) -> None:
-        _ = self._subcommand_reply_sender()
+        _ = self._require_report_sender()
 
-    async def _send_subcommand_reply(self, build_reply: Callable[[], bytes]) -> bytes:
-        return await self._subcommand_reply_sender().send_subcommand_reply(build_reply)
+    async def _send_subcommand_reply(
+        self,
+        build_reply: Callable[[], bytes | Awaitable[bytes]],
+    ) -> bytes:
+        if self._report_loop is not None:
+            return await self._report_loop.send_subcommand_reply(build_reply)
+        return await self._require_report_sender().send_subcommand_reply(build_reply)
 
-    def _subcommand_reply_sender(self) -> ReportLoop:
-        if self._report_loop is None:
+    def _require_report_sender(self) -> ReportSender:
+        if self._report_sender is None:
             msg = "gamepad is not open"
             raise ClosedError(msg)
-        return self._report_loop
+        return self._report_sender
 
     def _require_connected_for_input(self) -> None:
-        if self._report_loop is None or not self._connected_event.is_set():
+        if self._report_sender is None or not self._connected_event.is_set():
             msg = "gamepad is not connected"
             raise ClosedError(msg)
 
+    async def _send_direct_update(
+        self,
+        transform: Callable[[InputState], InputState],
+    ) -> None:
+        async with self._input_operation_lock:
+            self._require_connected_for_input()
+            candidate = transform(self._state_store.current)
+            await self._send_direct_candidate(candidate)
+
+    async def _send_direct_candidate(self, candidate: InputState) -> None:
+        self._controller_profile.validate_input_state(candidate)
+        await self._require_report_sender().send_input(
+            candidate,
+            reason="direct",
+            commit_state_store=self._state_store,
+        )
+
+    async def _tap_direct(self, *buttons: Button, duration: float) -> None:
+        async with self._input_operation_lock:
+            self._require_connected_for_input()
+            pressed = False
+            primary_error: BaseException | None = None
+            try:
+                press_state = self._state_store.current.with_buttons(
+                    (*self._state_store.current.buttons, *buttons)
+                )
+                await self._send_direct_candidate(press_state)
+                pressed = True
+                if duration > 0:
+                    await asyncio.sleep(duration)
+            except BaseException as error:
+                primary_error = error
+                raise
+            finally:
+                if pressed:
+                    release_state = self._state_store.current.with_buttons(
+                        self._state_store.current.buttons.difference(buttons)
+                    )
+                    try:
+                        await self._send_direct_candidate(release_state)
+                    except Exception as error:
+                        self._diagnostics.record_error(error, recoverable=True)
+                        if primary_error is None:
+                            raise
+
+    @staticmethod
+    def _validate_input_state(state: InputState) -> None:
+        if not isinstance(state, InputState):
+            msg = "state must be an InputState"
+            raise InvalidInputError(msg)
+
     @staticmethod
     def _validate_stick(name: str, value: Stick | None) -> None:
         if value is not None and not isinstance(value, Stick):
@@ -735,6 +856,7 @@ class ControllerRuntime:
             if self._report_loop is not None:
                 await self._report_loop.stop()
                 self._report_loop = None
+            self._report_sender = None
             if self._close_in_progress:
                 return
             if self._transport is not None and self._is_open:

swbt/report_loop.py

@@ -2,17 +2,119 @@
 
 import asyncio
 from collections import deque
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from contextlib import suppress
+from inspect import isawaitable
 from time import monotonic_ns
+from typing import cast
 
 from swbt.diagnostics import DiagnosticsRecorder
+from swbt.input import InputState
 from swbt.protocol.input_report import InputReportBuilder
 from swbt.protocol.session import SwitchHidSession
 from swbt.state_store import InputStateStore
 from swbt.transport.base import HidDeviceTransport
 
 REPLY_PERIODIC_HOLDOFF_SECONDS = 0.3
+ReplyBuilder = Callable[[], bytes | Awaitable[bytes]]
+
+
+class ReportSender:
+    """Serialize input reports and subcommand replies for one HID session."""
+
+    def __init__(
+        self,
+        *,
+        transport: HidDeviceTransport,
+        input_report_builder: InputReportBuilder,
+        session: SwitchHidSession,
+        diagnostics: DiagnosticsRecorder | None = None,
+        clock_ns: Callable[[], int] = monotonic_ns,
+    ) -> None:
+        """Create a session-scoped serialized report sender."""
+        self._transport = transport
+        self._input_report_builder = input_report_builder
+        self._session = session
+        self._diagnostics = diagnostics
+        self._clock_ns = clock_ns
+        self._timer = 0
+        self._send_lock = asyncio.Lock()
+
+    async def send_input(
+        self,
+        state: InputState,
+        *,
+        reason: str = "input",
+        commit_state_store: InputStateStore | None = None,
+    ) -> None:
+        """Send one input state and optionally commit it before releasing the send lock."""
+        async with self._send_lock:
+            await self._send_input_locked(
+                state,
+                reason=reason,
+                commit_state_store=commit_state_store,
+            )
+
+    async def send_current_input(
+        self,
+        state_store: InputStateStore,
+        *,
+        reason: str = "input",
+    ) -> None:
+        """Snapshot and send the current input state under the shared send lock."""
+        async with self._send_lock:
+            state = await state_store.snapshot()
+            await self._send_input_locked(state, reason=reason)
+
+    async def send_subcommand_reply(self, build_report: ReplyBuilder) -> bytes:
+        """Build and send a subcommand reply under the shared send lock."""
+        async with self._send_lock:
+            built = build_report()
+            if isawaitable(built):
+                report = await cast("Awaitable[bytes]", built)
+            else:
+                report = built
+            await self._send_subcommand_report_locked(report)
+            return report
+
+    async def send_subcommand_report(self, report: bytes) -> None:
+        """Send an already-built subcommand reply under the shared send lock."""
+        async with self._send_lock:
+            await self._send_subcommand_report_locked(report)
+
+    async def _send_subcommand_report_locked(self, report: bytes) -> None:
+        reply = bytearray(report)
+        if reply and reply[0] == 0x21:
+            reply[1] = self._timer
+        await self._send_report(bytes(reply), reason="subcommand_reply")
+        if reply and reply[0] == 0x21:
+            self._advance_timer()
+
+    async def _send_input_locked(
+        self,
+        state: InputState,
+        *,
+        reason: str,
+        commit_state_store: InputStateStore | None = None,
+    ) -> None:
+        imu_block = self._session.encode_imu(state.imu_frames, now_ns=self._clock_ns())
+        report = self._input_report_builder.build_0x30(
+            state,
+            timer=self._timer,
+            imu_block=imu_block,
+        )
+        await self._send_report(report, reason=reason)
+        if commit_state_store is not None:
+            await commit_state_store.apply(state)
+        self._advance_timer()
+
+    async def _send_report(self, report: bytes, *, reason: str) -> None:
+        await self._transport.send_interrupt(report)
+        if self._diagnostics is not None:
+            self._diagnostics.record_report_tx(report_id=report[0], reason=reason)
+
+    def _advance_timer(self) -> None:
+        self._timer = (self._timer + 1) & 0xFF
 
 
 class ReportLoop:
@@ -28,19 +130,20 @@ class ReportLoop:
         report_period_us: int = 8000,
         diagnostics: DiagnosticsRecorder | None = None,
         clock_ns: Callable[[], int] = monotonic_ns,
+        sender: ReportSender | None = None,
     ) -> None:
         """Create a report loop helper."""
-        self._transport = transport
         self._state_store = state_store
         self._report_period_seconds = report_period_us / 1_000_000
-        self._input_report_builder = input_report_builder
-        self._session = session
-        self._clock_ns = clock_ns
-        self._diagnostics = diagnostics
+        self._sender = sender or ReportSender(
+            transport=transport,
+            input_report_builder=input_report_builder,
+            session=session,
+            diagnostics=diagnostics,
+            clock_ns=clock_ns,
+        )
         self._reply_queue: deque[bytes] = deque()
-        self._timer = 0
         self._periodic_holdoff_until = 0.0
-        self._send_lock = asyncio.Lock()
         self._task: asyncio.Task[None] | None = None
 
     def start(self) -> None:
@@ -61,16 +164,13 @@ class ReportLoop:
 
     async def send_current_input(self, *, reason: str = "input") -> None:
         """Send one 0x30 input report for the current state."""
-        async with self._send_lock:
-            await self._send_current_input_locked(reason=reason)
+        await self._sender.send_current_input(self._state_store, reason=reason)
 
-    async def send_subcommand_reply(self, build_report: Callable[[], bytes]) -> bytes:
+    async def send_subcommand_reply(self, build_report: ReplyBuilder) -> bytes:
         """Apply a subcommand transition and send its reply under the send lock."""
-        async with self._send_lock:
-            report = build_report()
-            await self._send_subcommand_reply_locked(report)
-            self._holdoff_periodic_after_reply()
-            return report
+        report = await self._sender.send_subcommand_reply(build_report)
+        self._holdoff_periodic_after_reply()
+        return report
 
     def queue_reply(self, report: bytes) -> None:
         """Queue one subcommand reply for priority transmission."""
@@ -78,48 +178,19 @@ class ReportLoop:
 
     async def send_next_report(self) -> None:
         """Send the next queued reply or current input report."""
-        async with self._send_lock:
-            if self._reply_queue:
-                await self._send_subcommand_reply_locked(self._reply_queue.popleft())
-                self._holdoff_periodic_after_reply()
-                return
-            if self._is_periodic_held_off():
-                return
-            await self._send_current_input_locked(reason="periodic")
-
-    async def _send_current_input_locked(self, *, reason: str) -> None:
-        state = await self._state_store.snapshot()
-        imu_block = self._session.encode_imu(state.imu_frames, now_ns=self._clock_ns())
-        report = self._input_report_builder.build_0x30(
-            state,
-            timer=self._timer,
-            imu_block=imu_block,
-        )
-        await self._send_report(report, reason=reason)
-        self._advance_timer()
-
-    async def _send_subcommand_reply_locked(self, report: bytes) -> None:
-        reply = bytearray(report)
-        if reply and reply[0] == 0x21:
-            reply[1] = self._timer
-        await self._send_report(bytes(reply), reason="subcommand_reply")
-        if reply and reply[0] == 0x21:
-            self._advance_timer()
+        if self._reply_queue:
+            await self._sender.send_subcommand_report(self._reply_queue.popleft())
+            self._holdoff_periodic_after_reply()
+            return
+        if self._is_periodic_held_off():
+            return
+        await self.send_current_input(reason="periodic")
 
     async def _run(self) -> None:
         while True:
             await asyncio.sleep(self._report_period_seconds)
             await self.send_next_report()
 
-    async def _send_report(self, report: bytes, *, reason: str) -> None:
-        await self._transport.send_interrupt(report)
-        report_id = report[0]
-        if self._diagnostics is not None:
-            self._diagnostics.record_report_tx(report_id=report_id, reason=reason)
-
-    def _advance_timer(self) -> None:
-        self._timer = (self._timer + 1) & 0xFF
-
     def _holdoff_periodic_after_reply(self) -> None:
         self._periodic_holdoff_until = (
             asyncio.get_running_loop().time() + REPLY_PERIODIC_HOLDOFF_SECONDS

{swbt_python-0.3.0.dist-info → swbt_python-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swbt-python
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python library for presenting an NX-compatible virtual Bluetooth HID input device.
 Keywords: bluetooth,bluetooth-hid,controller,gamepad,hid,nx
 Author: niart120

{swbt_python-0.3.0.dist-info → swbt_python-0.4.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
-swbt/__init__.py,sha256=94cScYM8xa8VeoR5OodUuwj3Vq6bOIBxKoMBIQ5Itlc,1170
+swbt/__init__.py,sha256=2IR5hiqRDZCUgDDcnXpzSX8lsGWcEX9gqOGgz1GUmUY,1410
 swbt/_testing/__init__.py,sha256=RtJg6CXFY42HTLehYp33Ilrliqhp4wOSN6cjIGoRE8A,58
-swbt/_testing/gamepad.py,sha256=n9jMFER-EnLwhHBEytyTUpoSMEDF0leghcmVVvoFNjs,2493
+swbt/_testing/gamepad.py,sha256=xibVgsA_Un0C1WZt6pIHOZXefoR27XOEMZxwLbufPJY,4514
 swbt/adapter_discovery.py,sha256=cvlMQgmvmR-wsB0jPe9bipBBxcIVbhO6NRkTAKnPBYA,7717
 swbt/diagnostics.py,sha256=HdOiBpZ8eAlESmibgsR_HLq5V0-OEDUpVUwJ1D9eN28,7281
 swbt/errors.py,sha256=rKQZs-EO_5BQPtrZSRpirc-6_ymyxt1Q04VZi8y29cI,3196
-swbt/gamepad/__init__.py,sha256=s3MMJ--NwtxmzlJKIgfiTfEtjYP8JTQv7Qs3OKJcYRM,446
+swbt/gamepad/__init__.py,sha256=4EQM1jG8Ev2UVjb9Zk3idlyYFZ1eLM5RqzHsurkV6z8,725
 swbt/gamepad/_config.py,sha256=4Tq3Jlzv9IoyhQ0sDEBmIZ-Fz1Upc4koE4vnTQHDgrg,3793
 swbt/gamepad/connection.py,sha256=My3deMw4L64UoEXjeyRNBs1D6UvrvkeC2P7yf_PLPYQ,7776
 swbt/gamepad/constants.py,sha256=gDesRFvVxZ3SMSiP4qzd42em_Dt9M5hIu3-2exgKEus,84
-swbt/gamepad/core.py,sha256=vGY24NsCxJ37XY3jagk6P1DZzDM1JJwXdggZM7fk1Ug,15042
-swbt/gamepad/interface.py,sha256=GgPo5VwFhvcPIDy265R_dOQSYrBN1MYekqyPvIuXWQY,9431
-swbt/gamepad/output.py,sha256=Et2efB09tkNZF50_0ANk-JjHTJsJBpbzSdsJeWMDtfA,4101
-swbt/gamepad/runtime.py,sha256=28wDzmCWWEihSLnzg2E0MYP73z3fIGoc2Vu98XZuH88,30508
+swbt/gamepad/core.py,sha256=eJei4mccT7cTLmMkR7TnAb4_gVj6aDqgG9tiJp-vTQU,17880
+swbt/gamepad/interface.py,sha256=Q_iU-te54mXumg7LypchVpmJb5qcn8hxGLMwVhKNNaE,10562
+swbt/gamepad/output.py,sha256=dx7xCBL83fs_jjgsdBVfji3pbalGqi92CwlbB7qzNxM,4173
+swbt/gamepad/runtime.py,sha256=1OD9xyPhWg4lFRjM21PAqjJC-hk--eBkHz9PIQRLY68,35584
 swbt/gamepad/transport_factory.py,sha256=2LLGIF3Bc4ufBNjp1AcdqNkHNP8ZBDFU2PNt898vo8o,2059
 swbt/imu.py,sha256=sT1_MsYECQlQ-pSfayD8gojD9l3w9zEtOI3xP1IovQM,4237
 swbt/input.py,sha256=7gv75lzrcmoV8Sijz7f1pvsheRrmUi_TCIMW3DjUVjw,22275
@@ -31,7 +31,7 @@ swbt/protocol/session.py,sha256=TtnnFySalCXsEUwVv0DX9w1E2xq1yFIfmgCrA6wGHzs,3758
 swbt/protocol/spi.py,sha256=buKyNYYOHOSYbpVh3Wa2968FL4VIO_43QcSXNowNfJs,2594
 swbt/protocol/subcommand.py,sha256=1Z3Xf8xo7AydhyTa3bHgHM24hN2YS37yp7eioOHTu0A,7633
 swbt/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-swbt/report_loop.py,sha256=3qGLLWpJo_lWMdYXkkLqajZrQJtTLF2w7Z1z7iruB8c,4903
+swbt/report_loop.py,sha256=HFAPdm9Wx8zBT-sqUn_zmLf6boahl_BsmoxfkifbmYE,7318
 swbt/state_store.py,sha256=Mf8uKR5CoQdzyMmqflNE_2KUWE_ZgmLaHcGXUcVThW4,2693
 swbt/transport/__init__.py,sha256=b_Vqsg0k_g7XclN9XHQrcJxqCwGIklxG5NqzISal4_I,68
 swbt/transport/_bumble_acl.py,sha256=RnueTwEgAd0w3YgxnXkw0AKQXMeECIRope96W-xQ1K8,1425
@@ -43,8 +43,8 @@ swbt/transport/_bumble_usb_devices.py,sha256=soAKiHTzeeTYdb7M357yaac-RxG2c_BiKWH
 swbt/transport/base.py,sha256=lAGAJjGMg5CwtdAKmefCZglWqT3mWzm7CFOOCGGKul4,5619
 swbt/transport/bumble.py,sha256=gB0vy1GW-1Mbg_EZuYSrdOKVClKyNEKXMy1jju41Bts,30147
 swbt/transport/fake.py,sha256=Pmr-9a3qg2v9Rs86wBjINdWmWi5KOZlcFMH3AOmWF58,12903
-swbt_python-0.3.0.dist-info/licenses/LICENSE,sha256=FzzUoYjuIh5DzpeaujIbDUTylYnyzcHRVU-_ZMyowyk,1065
-swbt_python-0.3.0.dist-info/WHEEL,sha256=uOqnPWqgFlbov4NeTCercq7cBQ2UN7xh5fiW55lOnAg,81
-swbt_python-0.3.0.dist-info/entry_points.txt,sha256=YYQc7VgoSy74iZ6s8Qr6iJpnvFoDpp8G4-v0KJH5TGo,48
-swbt_python-0.3.0.dist-info/METADATA,sha256=Dta7JIdGnIRn3tZ8xqguwesI8Vf94-4CIL5b-UMbHWA,5994
-swbt_python-0.3.0.dist-info/RECORD,,
+swbt_python-0.4.0.dist-info/licenses/LICENSE,sha256=FzzUoYjuIh5DzpeaujIbDUTylYnyzcHRVU-_ZMyowyk,1065
+swbt_python-0.4.0.dist-info/WHEEL,sha256=uOqnPWqgFlbov4NeTCercq7cBQ2UN7xh5fiW55lOnAg,81
+swbt_python-0.4.0.dist-info/entry_points.txt,sha256=YYQc7VgoSy74iZ6s8Qr6iJpnvFoDpp8G4-v0KJH5TGo,48
+swbt_python-0.4.0.dist-info/METADATA,sha256=CjgPwuJCCm3HlnkVf6vMZUnowaeEA0PxLPp3Eo026iI,5994
+swbt_python-0.4.0.dist-info/RECORD,,