swbt-python 0.1.0__py3-none-any.whl

swbt/report_loop.py

@@ -0,0 +1,115 @@
+"""Input report sender used by SwitchGamepad."""
+
+import asyncio
+from collections import deque
+from contextlib import suppress
+
+from swbt.diagnostics import DiagnosticsRecorder
+from swbt.protocol.input_report import InputReportBuilder
+from swbt.state_store import InputStateStore
+from swbt.transport.base import HidDeviceTransport
+
+REPLY_PERIODIC_HOLDOFF_SECONDS = 0.3
+
+
+class ReportLoop:
+    """Send input reports from the current input state."""
+
+    def __init__(
+        self,
+        *,
+        transport: HidDeviceTransport,
+        state_store: InputStateStore,
+        report_period_us: int = 8000,
+        input_report_builder: InputReportBuilder | None = None,
+        diagnostics: DiagnosticsRecorder | 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 or InputReportBuilder()
+        self._diagnostics = diagnostics
+        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:
+        """Start periodic input report transmission."""
+        if self._task is not None and not self._task.done():
+            return
+        self._task = asyncio.create_task(self._run(), name="swbt-report-loop")
+
+    async def stop(self) -> None:
+        """Stop periodic input report transmission."""
+        if self._task is None:
+            return
+        task = self._task
+        self._task = None
+        task.cancel()
+        with suppress(asyncio.CancelledError):
+            await task
+
+    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)
+
+    async def send_subcommand_reply(self, report: bytes) -> None:
+        """Send one 0x21 subcommand reply with the shared report timer."""
+        async with self._send_lock:
+            await self._send_subcommand_reply_locked(report)
+            self._holdoff_periodic_after_reply()
+
+    def queue_reply(self, report: bytes) -> None:
+        """Queue one subcommand reply for priority transmission."""
+        self._reply_queue.append(bytes(report))
+
+    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()
+        report = self._input_report_builder.build_0x30(state, timer=self._timer)
+        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()
+
+    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
+        )
+
+    def _is_periodic_held_off(self) -> bool:
+        return asyncio.get_running_loop().time() < self._periodic_holdoff_until

swbt/state_store.py

@@ -0,0 +1,60 @@
+"""Async-safe input state storage."""
+
+import asyncio
+
+from swbt.input import Button, IMUFrame, InputState, Stick
+
+
+class InputStateStore:
+    """Store the current immutable input state behind an async lock."""
+
+    def __init__(self, initial_state: InputState | None = None) -> None:
+        """Create a state store."""
+        self._state = initial_state or InputState.neutral()
+        self._lock = asyncio.Lock()
+
+    async def snapshot(self) -> InputState:
+        """Return the current input state."""
+        async with self._lock:
+            return self._state
+
+    @property
+    def current(self) -> InputState:
+        """Return the latest committed input state."""
+        return self._state
+
+    async def apply(self, state: InputState) -> InputState:
+        """Replace the current input state."""
+        async with self._lock:
+            self._state = state
+            return self._state
+
+    async def sticks(self, *, left: Stick | None = None, right: Stick | None = None) -> InputState:
+        """Replace one or both stick positions."""
+        async with self._lock:
+            self._state = self._state.with_sticks(left_stick=left, right_stick=right)
+            return self._state
+
+    async def imu(self, *frames: IMUFrame) -> InputState:
+        """Replace IMU frames."""
+        async with self._lock:
+            self._state = self._state.with_imu(*frames)
+            return self._state
+
+    async def press(self, *buttons: Button) -> InputState:
+        """Add buttons to the current input state."""
+        async with self._lock:
+            self._state = self._state.with_buttons((*self._state.buttons, *buttons))
+            return self._state
+
+    async def release(self, *buttons: Button) -> InputState:
+        """Remove buttons from the current input state."""
+        async with self._lock:
+            self._state = self._state.with_buttons(self._state.buttons.difference(buttons))
+            return self._state
+
+    async def neutral(self) -> InputState:
+        """Replace the current input state with neutral input."""
+        async with self._lock:
+            self._state = InputState.neutral()
+            return self._state

swbt/transport/__init__.py

@@ -0,0 +1,3 @@
+"""HID transport implementations."""
+
+__all__: tuple[str, ...] = ()

swbt/transport/_bumble_acl.py

@@ -0,0 +1,33 @@
+"""ACL queue drain helper for Bumble HID transport."""
+
+from collections.abc import Awaitable
+
+
+async def drain_bumble_acl_queue(l2cap_channel: object) -> None:
+    """Wait until Bumble reports no pending ACL packets for the channel."""
+    connection = getattr(l2cap_channel, "connection", None)
+    connection_handle = getattr(connection, "handle", None)
+    acl_packet_queue = getattr(connection, "acl_packet_queue", None)
+    if acl_packet_queue is None and isinstance(connection_handle, int):
+        device = getattr(connection, "device", None)
+        host = getattr(device, "host", None)
+        get_data_packet_queue = getattr(host, "get_data_packet_queue", None)
+        if callable(get_data_packet_queue):
+            acl_packet_queue = get_data_packet_queue(connection_handle)
+    drain = getattr(acl_packet_queue, "drain", None)
+    if not isinstance(connection_handle, int) or not callable(drain):
+        return
+    try:
+        last_pending: int | None = None
+        while True:
+            pending = getattr(acl_packet_queue, "pending", 0)
+            if not isinstance(pending, int) or pending <= 0 or pending == last_pending:
+                return
+            last_pending = pending
+            drain_result = drain(connection_handle)
+            if isinstance(drain_result, Awaitable):
+                await drain_result
+                continue
+            return
+    except ValueError:
+        return

swbt/transport/_bumble_hidp.py

@@ -0,0 +1,34 @@
+"""HIDP helpers for Bumble HID transport."""
+
+HID_OUTPUT_REPORT_TYPE = 0x02
+HIDP_DATA_MESSAGE_TYPE = 0x0A
+HID_GET_SET_SUCCESS = 0xFF
+HID_GET_SET_UNSUPPORTED_REQUEST = 0x02
+HID_CONTROL_PSM = 0x0011
+HID_INTERRUPT_PSM = 0x0013
+
+
+def decode_hidp_output_report(pdu: bytes) -> bytes | None:
+    if not pdu:
+        return None
+    message_type = pdu[0] >> 4
+    report_type = pdu[0] & 0x03
+    if message_type != HIDP_DATA_MESSAGE_TYPE:
+        return None
+    if report_type != HID_OUTPUT_REPORT_TYPE:
+        return None
+    return pdu[1:]
+
+
+def hid_channel_name(psm: object) -> str:
+    if psm == HID_CONTROL_PSM:
+        return "control"
+    if psm == HID_INTERRUPT_PSM:
+        return "interrupt"
+    return "unknown"
+
+
+def format_psm(psm: object) -> str:
+    if isinstance(psm, int):
+        return f"0x{psm:04x}"
+    return "unknown"

swbt/transport/_bumble_key_store.py

@@ -0,0 +1,220 @@
+"""Bumble JSON key store metadata helpers."""
+
+import copy
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol, cast
+
+from swbt.diagnostics import DiagnosticsRecorder
+from swbt.errors import InvalidKeyStoreError
+
+PREVIOUS_NAMESPACE_PREFIX = "swbt.previous::"
+
+
+@dataclass(frozen=True)
+class KeyStoreMetadata:
+    """Observed metadata for a Bumble JSON key store file."""
+
+    exists: bool
+    previous_exists: bool
+
+
+def read_key_store_metadata(key_store_path: str | Path) -> KeyStoreMetadata:
+    """Read non-sensitive metadata from a Bumble JSON key store file."""
+    path = Path(key_store_path)
+    if not path.exists():
+        return KeyStoreMetadata(exists=False, previous_exists=False)
+    return KeyStoreMetadata(
+        exists=True,
+        previous_exists=_previous_generation_exists(path),
+    )
+
+
+def _previous_generation_exists(key_store_path: Path) -> bool:
+    try:
+        key_store_data = json.loads(key_store_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if not isinstance(key_store_data, dict):
+        return False
+    return any(str(namespace).startswith(PREVIOUS_NAMESPACE_PREFIX) for namespace in key_store_data)
+
+
+class _BumbleJsonKeyStoreRuntime(Protocol):
+    namespace: str
+
+    async def load(
+        self,
+    ) -> tuple[dict[str, dict[str, dict[str, object]]], dict[str, dict[str, object]]]:
+        """Load the full JSON DB and this store's current key map."""
+
+    async def save(self, db: dict[str, dict[str, dict[str, object]]]) -> None:
+        """Save the full JSON DB."""
+
+    async def get(self, name: str) -> object | None:
+        """Return one key entry."""
+
+    async def get_all(self) -> list[tuple[str, object]]:
+        """Return all current key entries."""
+
+    async def delete(self, name: str) -> None:
+        """Delete one current key entry."""
+
+    async def delete_all(self) -> None:
+        """Delete all current key entries."""
+
+    async def get_resolving_keys(self) -> object:
+        """Return LE resolving keys for Bumble internals."""
+
+
+class _CurrentPreviousJsonKeyStore:
+    """Bumble-compatible JSON key store with one previous generation."""
+
+    def __init__(
+        self,
+        *,
+        filename: str | Path,
+        namespace: str | None = None,
+        device: object | None = None,
+    ) -> None:
+        if namespace is None and device is None:
+            msg = "namespace or device is required"
+            raise ValueError(msg)
+        self._filename = Path(filename)
+        self._namespace = namespace
+        self._device = device
+        self.last_update_previous_saved = False
+
+    @classmethod
+    def from_device(
+        cls,
+        device: object,
+        *,
+        filename: str | Path,
+    ) -> "_CurrentPreviousJsonKeyStore":
+        """Create a store whose namespace follows the Bumble device address."""
+        return cls(filename=filename, device=device)
+
+    async def update(self, name: str, keys: object) -> None:
+        """Write current keys and keep the overwritten current value as previous."""
+        current_store = self._current_store()
+        db, current_key_map = await current_store.load()
+        previous_namespace = self._previous_namespace(current_store)
+        previous_key_map = copy.deepcopy(current_key_map)
+        self.last_update_previous_saved = bool(previous_key_map)
+        if previous_key_map:
+            db[previous_namespace] = previous_key_map
+        else:
+            db.pop(previous_namespace, None)
+        current_key_map.clear()
+        current_key_map[name] = cast("Any", keys).to_dict()
+        await current_store.save(db)
+
+    async def get(self, name: str) -> object | None:
+        """Return one current key entry."""
+        for peer_address, peer_keys in await self.get_all():
+            if peer_address == name:
+                return peer_keys
+        return None
+
+    async def get_all(self) -> list[tuple[str, object]]:
+        """Return current key entries only."""
+        entries = await self._current_store().get_all()
+        if len(entries) > 1:
+            msg = "key store contains multiple current peers"
+            raise InvalidKeyStoreError(msg)
+        return entries
+
+    async def delete(self, name: str) -> None:
+        """Delete one current key entry."""
+        await self._current_store().delete(name)
+
+    async def delete_all(self) -> None:
+        """Delete all current key entries."""
+        await self._current_store().delete_all()
+
+    async def get_resolving_keys(self) -> object:
+        """Return current LE resolving keys for Bumble internals."""
+        return await self._current_store().get_resolving_keys()
+
+    def _current_store(self) -> _BumbleJsonKeyStoreRuntime:
+        from bumble.keys import JsonKeyStore  # noqa: PLC0415
+
+        if self._device is not None:
+            return cast(
+                "_BumbleJsonKeyStoreRuntime",
+                JsonKeyStore.from_device(
+                    cast("Any", self._device),
+                    filename=str(self._filename),
+                ),
+            )
+        return cast(
+            "_BumbleJsonKeyStoreRuntime",
+            JsonKeyStore(self._namespace, str(self._filename)),
+        )
+
+    def _previous_namespace(self, current_store: object) -> str:
+        return f"{PREVIOUS_NAMESPACE_PREFIX}{cast('Any', current_store).namespace}"
+
+
+class _DiagnosticKeyStore:
+    """Key store wrapper that records write outcome without logging key material."""
+
+    def __init__(self, key_store: object, diagnostics: DiagnosticsRecorder) -> None:
+        self._key_store = key_store
+        self._diagnostics = diagnostics
+
+    async def update(self, name: str, keys: object) -> None:
+        """Record key-store write success or failure."""
+        try:
+            await cast("Any", self._key_store).update(name, keys)
+        except Exception as error:
+            fields = self._generation_fields()
+            self._diagnostics.record_event(
+                "key_store_update",
+                **fields,
+                error_type=type(error).__name__,
+                message=str(error),
+                peer_address=name,
+                status="failed",
+            )
+            raise
+        fields = self._generation_fields()
+        self._diagnostics.record_event(
+            "key_store_update",
+            **fields,
+            peer_address=name,
+            status="succeeded",
+        )
+
+    async def get(self, name: str) -> object | None:
+        """Delegate key lookup."""
+        return await cast("Any", self._key_store).get(name)
+
+    async def get_all(self) -> list[tuple[str, object]]:
+        """Delegate full key listing."""
+        return await cast("Any", self._key_store).get_all()
+
+    async def delete(self, name: str) -> None:
+        """Delegate key deletion."""
+        await cast("Any", self._key_store).delete(name)
+
+    async def delete_all(self) -> None:
+        """Delegate all-key deletion."""
+        await cast("Any", self._key_store).delete_all()
+
+    async def get_resolving_keys(self) -> object:
+        """Delegate LE resolving-key lookup for Bumble internals."""
+        return await cast("Any", self._key_store).get_resolving_keys()
+
+    def __getattr__(self, name: str) -> object:
+        return getattr(self._key_store, name)
+
+    def _generation_fields(self) -> dict[str, object]:
+        if not isinstance(self._key_store, _CurrentPreviousJsonKeyStore):
+            return {}
+        return {
+            "generation": "current",
+            "previous_saved": self._key_store.last_update_previous_saved,
+        }