swbt-python 0.1.0__py3-none-any.whl

swbt/gamepad/output.py

@@ -0,0 +1,73 @@
+"""Output report dispatch for SwitchGamepad."""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+
+from swbt.diagnostics import DiagnosticsRecorder
+from swbt.protocol.output_report import OutputReportParser
+from swbt.protocol.subcommand import SubcommandResponder, UnsupportedSubcommandError
+from swbt.state_store import InputStateStore
+
+ReplySender = Callable[[bytes], Awaitable[None]]
+ReplySenderRequirement = Callable[[], None]
+
+
+@dataclass
+class OutputReportDispatcher:
+    """Parse host output reports, record diagnostics, and enqueue replies."""
+
+    diagnostics: DiagnosticsRecorder
+    require_reply_sender: ReplySenderRequirement
+    send_subcommand_reply: ReplySender
+    state_store: InputStateStore
+    output_report_parser: OutputReportParser = field(default_factory=OutputReportParser)
+    subcommand_responder: SubcommandResponder = field(default_factory=SubcommandResponder)
+
+    async def dispatch(self, payload: bytes) -> None:
+        """Handle one host-to-device output report payload."""
+        output_report = self.output_report_parser.parse(payload)
+        subcommand_id = _format_subcommand_id(output_report.subcommand_id)
+        if output_report.rumble is not None:
+            self.diagnostics.record_raw_rumble(output_report.rumble)
+        self.diagnostics.record_event(
+            "output_report_rx",
+            length=len(payload),
+            packet_id=output_report.packet_id,
+            report_id=_format_report_id(output_report.report_id),
+            subcommand_id=subcommand_id,
+        )
+        if output_report.subcommand_id is None:
+            return
+        self.diagnostics.record_subcommand_rx(
+            packet_id=output_report.packet_id,
+            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)
+        except UnsupportedSubcommandError:
+            self.diagnostics.record_event(
+                "unsupported_subcommand",
+                packet_id=output_report.packet_id,
+                payload=output_report.subcommand_payload.hex(),
+                subcommand_id=subcommand_id,
+            )
+            raise
+        self.diagnostics.record_event(
+            "subcommand_reply_tx",
+            packet_id=output_report.packet_id,
+            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:
+    return f"0x{report_id:02x}"
+
+
+def _format_subcommand_id(subcommand_id: int | None) -> str | None:
+    if subcommand_id is None:
+        return None
+    return f"0x{subcommand_id:02x}"

swbt/gamepad/transport_factory.py

@@ -0,0 +1,22 @@
+"""Default transport factory for SwitchGamepad."""
+
+from swbt.diagnostics import DiagnosticsRecorder
+from swbt.transport.base import HidDeviceTransport
+
+
+def create_default_transport(
+    *,
+    adapter: str,
+    device_name: str,
+    diagnostics: DiagnosticsRecorder,
+    key_store_path: str | None,
+) -> HidDeviceTransport:
+    """Create the default Bumble-backed transport without importing Bumble at API import time."""
+    from swbt.transport.bumble import BumbleHidTransport  # noqa: PLC0415
+
+    return BumbleHidTransport(
+        adapter=adapter,
+        device_name=device_name,
+        diagnostics=diagnostics,
+        key_store_path=key_store_path,
+    )

swbt/input.py

@@ -0,0 +1,550 @@
+"""Input state value objects."""
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum, auto
+
+from swbt.errors import InvalidInputError
+
+
+class Button(Enum):
+    """Buttons exposed by the input model.
+
+    Each member maps to one supported gamepad button. The HID bit positions are
+    defined by the protocol layer and its tests, not by the enum values.
+    """
+
+    A = auto()
+    B = auto()
+    X = auto()
+    Y = auto()
+    L = auto()
+    R = auto()
+    ZL = auto()
+    ZR = auto()
+    PLUS = auto()
+    MINUS = auto()
+    HOME = auto()
+    CAPTURE = auto()
+    LEFT_STICK = auto()
+    RIGHT_STICK = auto()
+    DPAD_UP = auto()
+    DPAD_DOWN = auto()
+    DPAD_LEFT = auto()
+    DPAD_RIGHT = auto()
+
+
+@dataclass(frozen=True)
+class Stick:
+    """12-bit raw stick position.
+
+    Attributes:
+        x: Horizontal raw axis value in the inclusive ``0..4095`` range.
+        y: Vertical raw axis value in the inclusive ``0..4095`` range.
+    """
+
+    x: int
+    y: int
+
+    MIN = 0
+    CENTER = 2048
+    MAX = 4095
+
+    def __post_init__(self) -> None:
+        """Validate direct dataclass construction."""
+        self._validate_axis("x", self.x)
+        self._validate_axis("y", self.y)
+
+    @classmethod
+    def center(cls) -> "Stick":
+        """Return the neutral stick position.
+
+        Returns:
+            Stick: Centered stick with both axes set to ``CENTER``.
+        """
+        return cls(x=cls.CENTER, y=cls.CENTER)
+
+    @classmethod
+    def raw(cls, *, x: int, y: int) -> "Stick":
+        """Return a stick position from 12-bit raw values.
+
+        Args:
+            x: Horizontal raw axis value.
+            y: Vertical raw axis value.
+
+        Returns:
+            Stick: Stick position with the supplied raw axis values.
+
+        Raises:
+            InvalidInputError: Either axis is outside the supported raw range.
+        """
+        cls._validate_axis("x", x)
+        cls._validate_axis("y", y)
+        return cls(x=x, y=y)
+
+    @classmethod
+    def normalized(cls, *, x: float, y: float) -> "Stick":
+        """Return a stick position from normalized axis values.
+
+        Args:
+            x: Horizontal value in the inclusive ``-1.0..1.0`` range.
+            y: Vertical value in the inclusive ``-1.0..1.0`` range.
+
+        Returns:
+            Stick: Raw stick position converted from normalized values.
+
+        Raises:
+            InvalidInputError: Either normalized axis is outside the supported range.
+        """
+        return cls.raw(
+            x=cls._normalized_axis_to_raw("x", x),
+            y=cls._normalized_axis_to_raw("y", y),
+        )
+
+    @classmethod
+    def tilt(cls, x: float, y: float) -> "Stick":
+        """Return a stick position from normalized tilt values.
+
+        Args:
+            x: Horizontal tilt in the inclusive ``-1.0..1.0`` range.
+            y: Vertical tilt in the inclusive ``-1.0..1.0`` range.
+
+        Returns:
+            Stick: Raw stick position converted from normalized tilt values.
+
+        Raises:
+            InvalidInputError: Either tilt axis is outside the supported range.
+        """
+        return cls.normalized(x=x, y=y)
+
+    @classmethod
+    def up(cls, amount: float = 1.0) -> "Stick":
+        """Return an upward stick tilt.
+
+        Args:
+            amount: Tilt amount in the inclusive ``0.0..1.0`` range.
+
+        Returns:
+            Stick: Stick tilted upward by ``amount``.
+
+        Raises:
+            InvalidInputError: ``amount`` is outside the supported range.
+        """
+        cls._validate_amount(amount)
+        return cls.tilt(0.0, amount)
+
+    @classmethod
+    def down(cls, amount: float = 1.0) -> "Stick":
+        """Return a downward stick tilt.
+
+        Args:
+            amount: Tilt amount in the inclusive ``0.0..1.0`` range.
+
+        Returns:
+            Stick: Stick tilted downward by ``amount``.
+
+        Raises:
+            InvalidInputError: ``amount`` is outside the supported range.
+        """
+        cls._validate_amount(amount)
+        return cls.tilt(0.0, -amount)
+
+    @classmethod
+    def left(cls, amount: float = 1.0) -> "Stick":
+        """Return a leftward stick tilt.
+
+        Args:
+            amount: Tilt amount in the inclusive ``0.0..1.0`` range.
+
+        Returns:
+            Stick: Stick tilted left by ``amount``.
+
+        Raises:
+            InvalidInputError: ``amount`` is outside the supported range.
+        """
+        cls._validate_amount(amount)
+        return cls.tilt(-amount, 0.0)
+
+    @classmethod
+    def right(cls, amount: float = 1.0) -> "Stick":
+        """Return a rightward stick tilt.
+
+        Args:
+            amount: Tilt amount in the inclusive ``0.0..1.0`` range.
+
+        Returns:
+            Stick: Stick tilted right by ``amount``.
+
+        Raises:
+            InvalidInputError: ``amount`` is outside the supported range.
+        """
+        cls._validate_amount(amount)
+        return cls.tilt(amount, 0.0)
+
+    @classmethod
+    def _validate_axis(cls, axis_name: str, value: int) -> None:
+        if not cls.MIN <= value <= cls.MAX:
+            msg = f"{axis_name} must be between {cls.MIN} and {cls.MAX}: {value}"
+            raise InvalidInputError(msg)
+
+    @classmethod
+    def _normalized_axis_to_raw(cls, axis_name: str, value: float) -> int:
+        if not -1.0 <= value <= 1.0:
+            msg = f"{axis_name} must be between -1.0 and 1.0: {value}"
+            raise InvalidInputError(msg)
+        if value < 0:
+            return cls.CENTER + round(value * (cls.CENTER - cls.MIN))
+        return cls.CENTER + round(value * (cls.MAX - cls.CENTER))
+
+    @classmethod
+    def _validate_amount(cls, value: float) -> None:
+        if not 0.0 <= value <= 1.0:
+            msg = f"amount must be between 0.0 and 1.0: {value}"
+            raise InvalidInputError(msg)
+
+
+@dataclass(frozen=True)
+class IMUFrame:
+    """One 6-axis IMU frame.
+
+    Attributes:
+        accel_x: Accelerometer X-axis raw value.
+        accel_y: Accelerometer Y-axis raw value.
+        accel_z: Accelerometer Z-axis raw value.
+        gyro_x: Gyroscope X-axis raw value.
+        gyro_y: Gyroscope Y-axis raw value.
+        gyro_z: Gyroscope Z-axis raw value.
+    """
+
+    accel_x: int
+    accel_y: int
+    accel_z: int
+    gyro_x: int
+    gyro_y: int
+    gyro_z: int
+
+    MIN = -32768
+    MAX = 32767
+
+    def __post_init__(self) -> None:
+        """Validate direct dataclass construction."""
+        for field_name in (
+            "accel_x",
+            "accel_y",
+            "accel_z",
+            "gyro_x",
+            "gyro_y",
+            "gyro_z",
+        ):
+            self._validate_i16(field_name, getattr(self, field_name))
+
+    @classmethod
+    def neutral(cls) -> "IMUFrame":
+        """Return an IMU frame with no movement.
+
+        Returns:
+            IMUFrame: Frame with all accelerometer and gyroscope values set to zero.
+        """
+        return cls(accel_x=0, accel_y=0, accel_z=0, gyro_x=0, gyro_y=0, gyro_z=0)
+
+    @classmethod
+    def raw(
+        cls,
+        *,
+        accel: tuple[int, int, int] | None = None,
+        gyro: tuple[int, int, int] | None = None,
+    ) -> "IMUFrame":
+        """Return an IMU frame from raw accelerometer and gyroscope axes.
+
+        Args:
+            accel: Optional accelerometer ``(x, y, z)`` raw values.
+            gyro: Optional gyroscope ``(x, y, z)`` raw values.
+
+        Returns:
+            IMUFrame: Frame with omitted sensor axes set to zero.
+
+        Raises:
+            InvalidInputError: A supplied axis tuple does not contain three values
+                or any value is outside the supported signed 16-bit range.
+        """
+        accel_x, accel_y, accel_z = cls._defaulted_axes("accel", accel)
+        gyro_x, gyro_y, gyro_z = cls._defaulted_axes("gyro", gyro)
+        return cls(
+            accel_x=accel_x,
+            accel_y=accel_y,
+            accel_z=accel_z,
+            gyro_x=gyro_x,
+            gyro_y=gyro_y,
+            gyro_z=gyro_z,
+        )
+
+    @classmethod
+    def gyro(cls, x: int = 0, y: int = 0, z: int = 0) -> "IMUFrame":
+        """Return an IMU frame with only gyroscope axes set.
+
+        Args:
+            x: Gyroscope X-axis raw value.
+            y: Gyroscope Y-axis raw value.
+            z: Gyroscope Z-axis raw value.
+
+        Returns:
+            IMUFrame: Frame with gyroscope values set and accelerometer values zeroed.
+
+        Raises:
+            InvalidInputError: Any value is outside the supported signed 16-bit range.
+        """
+        return cls.raw(gyro=(x, y, z))
+
+    @classmethod
+    def accel(cls, x: int = 0, y: int = 0, z: int = 0) -> "IMUFrame":
+        """Return an IMU frame with only accelerometer axes set.
+
+        Args:
+            x: Accelerometer X-axis raw value.
+            y: Accelerometer Y-axis raw value.
+            z: Accelerometer Z-axis raw value.
+
+        Returns:
+            IMUFrame: Frame with accelerometer values set and gyroscope values zeroed.
+
+        Raises:
+            InvalidInputError: Any value is outside the supported signed 16-bit range.
+        """
+        return cls.raw(accel=(x, y, z))
+
+    def with_gyro(self, x: int = 0, y: int = 0, z: int = 0) -> "IMUFrame":
+        """Return a frame with replaced gyroscope axes.
+
+        Args:
+            x: Replacement gyroscope X-axis raw value.
+            y: Replacement gyroscope Y-axis raw value.
+            z: Replacement gyroscope Z-axis raw value.
+
+        Returns:
+            IMUFrame: Copy of this frame with accelerometer axes preserved.
+
+        Raises:
+            InvalidInputError: Any value is outside the supported signed 16-bit range.
+        """
+        return IMUFrame.raw(
+            accel=(self.accel_x, self.accel_y, self.accel_z),
+            gyro=(x, y, z),
+        )
+
+    def with_accel(self, x: int = 0, y: int = 0, z: int = 0) -> "IMUFrame":
+        """Return a frame with replaced accelerometer axes.
+
+        Args:
+            x: Replacement accelerometer X-axis raw value.
+            y: Replacement accelerometer Y-axis raw value.
+            z: Replacement accelerometer Z-axis raw value.
+
+        Returns:
+            IMUFrame: Copy of this frame with gyroscope axes preserved.
+
+        Raises:
+            InvalidInputError: Any value is outside the supported signed 16-bit range.
+        """
+        return IMUFrame.raw(
+            accel=(x, y, z),
+            gyro=(self.gyro_x, self.gyro_y, self.gyro_z),
+        )
+
+    @classmethod
+    def _validate_i16(cls, field_name: str, value: object) -> int:
+        if not isinstance(value, int) or not cls.MIN <= value <= cls.MAX:
+            msg = f"{field_name} must be an int between {cls.MIN} and {cls.MAX}: {value}"
+            raise InvalidInputError(msg)
+        return value
+
+    @classmethod
+    def _defaulted_axes(
+        cls,
+        name: str,
+        values: tuple[int, int, int] | None,
+    ) -> tuple[int, int, int]:
+        if values is None:
+            return (0, 0, 0)
+        return cls._validate_axes(name, values)
+
+    @classmethod
+    def _validate_axes(cls, name: str, values: object) -> tuple[int, int, int]:
+        if not isinstance(values, tuple) or len(values) != 3:
+            msg = f"{name} must be a tuple of three raw values"
+            raise InvalidInputError(msg)
+        x, y, z = values
+        return (
+            cls._validate_i16(f"{name}_x", x),
+            cls._validate_i16(f"{name}_y", y),
+            cls._validate_i16(f"{name}_z", z),
+        )
+
+
+@dataclass(frozen=True)
+class InputState:
+    """Immutable controller input state.
+
+    Attributes:
+        buttons: Pressed buttons represented as an immutable set.
+        left_stick: Current left stick position.
+        right_stick: Current right stick position.
+        imu_frames: Three IMU frames included in the next input report.
+    """
+
+    buttons: frozenset[Button]
+    left_stick: Stick
+    right_stick: Stick
+    imu_frames: tuple[IMUFrame, IMUFrame, IMUFrame]
+
+    @classmethod
+    def neutral(cls) -> "InputState":
+        """Return a state with no buttons pressed and centered sticks.
+
+        Returns:
+            InputState: Neutral state with centered sticks and neutral IMU frames.
+        """
+        neutral_imu = IMUFrame.neutral()
+        return cls(
+            buttons=frozenset(),
+            left_stick=Stick.center(),
+            right_stick=Stick.center(),
+            imu_frames=(neutral_imu, neutral_imu, neutral_imu),
+        )
+
+    def with_buttons(self, buttons: Iterable[Button]) -> "InputState":
+        """Return a state with a replaced button set.
+
+        Args:
+            buttons: Buttons that should be pressed in the returned state.
+
+        Returns:
+            InputState: Copy of this state with the supplied button set.
+        """
+        return InputState(
+            buttons=frozenset(buttons),
+            left_stick=self.left_stick,
+            right_stick=self.right_stick,
+            imu_frames=self.imu_frames,
+        )
+
+    def with_sticks(
+        self,
+        *,
+        left_stick: Stick | None = None,
+        right_stick: Stick | None = None,
+    ) -> "InputState":
+        """Return a state with replaced stick values.
+
+        Args:
+            left_stick: Optional replacement for the left stick.
+            right_stick: Optional replacement for the right stick.
+
+        Returns:
+            InputState: Copy of this state with supplied stick replacements.
+        """
+        return InputState(
+            buttons=self.buttons,
+            left_stick=left_stick if left_stick is not None else self.left_stick,
+            right_stick=right_stick if right_stick is not None else self.right_stick,
+            imu_frames=self.imu_frames,
+        )
+
+    def with_imu(self, *frames: IMUFrame) -> "InputState":
+        """Return a state with replaced IMU frames.
+
+        Args:
+            frames: One frame to repeat across all three IMU slots, or exactly three
+                frames to store in order.
+
+        Returns:
+            InputState: Copy of this state with supplied IMU frames.
+
+        Raises:
+            InvalidInputError: The frame count is not one or three, or any value is
+                not an ``IMUFrame``.
+        """
+        return InputState(
+            buttons=self.buttons,
+            left_stick=self.left_stick,
+            right_stick=self.right_stick,
+            imu_frames=self._normalize_imu_frames(frames),
+        )
+
+    def with_gyro(self, *samples: tuple[int, int, int]) -> "InputState":
+        """Return a state with replaced gyroscope axes.
+
+        Args:
+            samples: One ``(x, y, z)`` sample to repeat across all frames, or exactly
+                three samples to apply in order.
+
+        Returns:
+            InputState: Copy of this state with accelerometer axes preserved.
+
+        Raises:
+            InvalidInputError: The sample count is not one or three, a sample is not a
+                three-value tuple, or any value is outside the signed 16-bit range.
+        """
+        normalized = self._normalize_imu_samples("gyro", samples)
+        return self.with_imu(
+            *(
+                frame.with_gyro(*sample)
+                for frame, sample in zip(self.imu_frames, normalized, strict=True)
+            )
+        )
+
+    def with_accel(self, *samples: tuple[int, int, int]) -> "InputState":
+        """Return a state with replaced accelerometer axes.
+
+        Args:
+            samples: One ``(x, y, z)`` sample to repeat across all frames, or exactly
+                three samples to apply in order.
+
+        Returns:
+            InputState: Copy of this state with gyroscope axes preserved.
+
+        Raises:
+            InvalidInputError: The sample count is not one or three, a sample is not a
+                three-value tuple, or any value is outside the signed 16-bit range.
+        """
+        normalized = self._normalize_imu_samples("accel", samples)
+        return self.with_imu(
+            *(
+                frame.with_accel(*sample)
+                for frame, sample in zip(self.imu_frames, normalized, strict=True)
+            )
+        )
+
+    @staticmethod
+    def _normalize_imu_frames(
+        frames: tuple[IMUFrame, ...],
+    ) -> tuple[IMUFrame, IMUFrame, IMUFrame]:
+        if len(frames) == 1:
+            frame = frames[0]
+            if not isinstance(frame, IMUFrame):
+                msg = "frames must contain IMUFrame values"
+                raise InvalidInputError(msg)
+            return (frame, frame, frame)
+        if len(frames) == 3:
+            frame1, frame2, frame3 = frames
+            if not all(isinstance(frame, IMUFrame) for frame in frames):
+                msg = "frames must contain IMUFrame values"
+                raise InvalidInputError(msg)
+            return (frame1, frame2, frame3)
+        msg = f"expected 1 or 3 IMU frames, got {len(frames)}"
+        raise InvalidInputError(msg)
+
+    @staticmethod
+    def _normalize_imu_samples(
+        name: str,
+        samples: tuple[tuple[int, int, int], ...],
+    ) -> tuple[tuple[int, int, int], tuple[int, int, int], tuple[int, int, int]]:
+        if len(samples) == 1:
+            sample = IMUFrame._validate_axes(name, samples[0])
+            return (sample, sample, sample)
+        if len(samples) == 3:
+            sample1, sample2, sample3 = (
+                IMUFrame._validate_axes(name, sample) for sample in samples
+            )
+            return (sample1, sample2, sample3)
+        msg = f"expected 1 or 3 IMU {name} samples, got {len(samples)}"
+        raise InvalidInputError(msg)