swbt-python 0.1.0__py3-none-any.whl

swbt/transport/fake.py

@@ -0,0 +1,315 @@
+"""In-memory HID transport for integration tests."""
+
+import asyncio
+from typing import Literal
+
+from swbt.errors import ClosedError, InvalidKeyStoreError
+from swbt.transport.base import (
+    BondedPeer,
+    ConnectedCallback,
+    ControlDataCallback,
+    DisconnectedCallback,
+    DisconnectRequestResult,
+    InterruptDataCallback,
+)
+
+
+class FakeHidTransport:
+    """Record transport operations without opening Bluetooth resources."""
+
+    def __init__(
+        self,
+        *,
+        disconnect_request_auto_complete: bool = True,
+        disconnect_request_error: Exception | None = None,
+        bonded_peer_addresses: tuple[str, ...] = (),
+        active_reconnect_auto_connect: bool = True,
+        active_reconnect_error: BaseException | None = None,
+        send_interrupt_error: Exception | None = None,
+        close_wait: asyncio.Event | None = None,
+    ) -> None:
+        """Create a closed fake transport."""
+        self._is_open = False
+        self._open_count = 0
+        self._close_count = 0
+        self._disconnect_request_auto_complete = disconnect_request_auto_complete
+        self._disconnect_request_error = disconnect_request_error
+        self._bonded_peer_addresses = tuple(bonded_peer_addresses)
+        self._active_reconnect_auto_connect = active_reconnect_auto_connect
+        self._active_reconnect_error = active_reconnect_error
+        self._send_interrupt_error = send_interrupt_error
+        self._close_wait = close_wait
+        self._events: list[str] = []
+        self._control_channel_open = False
+        self._interrupt_channel_open = False
+        self._connected_emitted = False
+        self._disconnect_request_sent_interrupt_count: int | None = None
+        self._sent_interrupt_reports: list[bytes] = []
+        self._sent_control_reports: list[bytes] = []
+        self._interrupt_report_event = asyncio.Event()
+        self._disconnect_request_event = asyncio.Event()
+        self._close_start_event = asyncio.Event()
+        self._interrupt_callback: InterruptDataCallback | None = None
+        self._control_callback: ControlDataCallback | None = None
+        self._connected_callback: ConnectedCallback | None = None
+        self._disconnected_callback: DisconnectedCallback | None = None
+
+    @property
+    def is_open(self) -> bool:
+        """Return whether the fake transport is open."""
+        return self._is_open
+
+    @property
+    def open_count(self) -> int:
+        """Return the number of state-changing open calls."""
+        return self._open_count
+
+    @property
+    def close_count(self) -> int:
+        """Return the number of state-changing close calls."""
+        return self._close_count
+
+    @property
+    def events(self) -> tuple[str, ...]:
+        """Return transport lifecycle events in order."""
+        return tuple(self._events)
+
+    @property
+    def sent_interrupt_reports(self) -> tuple[bytes, ...]:
+        """Return interrupt reports sent by the gamepad."""
+        return tuple(self._sent_interrupt_reports)
+
+    @property
+    def sent_control_reports(self) -> tuple[bytes, ...]:
+        """Return control reports sent by the gamepad."""
+        return tuple(self._sent_control_reports)
+
+    @property
+    def disconnect_request_sent_interrupt_count(self) -> int | None:
+        """Return how many interrupt reports existed when disconnect was requested."""
+        return self._disconnect_request_sent_interrupt_count
+
+    async def open(self) -> None:
+        """Open the fake transport."""
+        if self._is_open:
+            return
+        self._is_open = True
+        self._open_count += 1
+        self._disconnect_request_sent_interrupt_count = None
+        self._disconnect_request_event.clear()
+        self._close_start_event.clear()
+        self._events.append("open")
+
+    async def start_advertising(self) -> None:
+        """Record an advertising transition."""
+        self._require_open()
+        self._events.append("start_advertising")
+
+    async def close(self) -> None:
+        """Close the fake transport."""
+        if not self._is_open:
+            return
+        self._close_start_event.set()
+        if self._close_wait is not None:
+            await self._close_wait.wait()
+        self._is_open = False
+        self._control_channel_open = False
+        self._interrupt_channel_open = False
+        self._connected_emitted = False
+        self._close_count += 1
+        self._events.append("close")
+
+    async def request_disconnect(self) -> DisconnectRequestResult:
+        """Record a best-effort remote disconnect request."""
+        self._require_open()
+        if self._disconnect_request_error is not None:
+            error = self._disconnect_request_error
+            self._events.append("request_disconnect_failed")
+            self._disconnect_request_event.set()
+            return DisconnectRequestResult(
+                status="failed",
+                error_type=type(error).__name__,
+                message=str(error),
+            )
+        if not self._control_channel_open and not self._interrupt_channel_open:
+            self._events.append("request_disconnect_unavailable")
+            self._disconnect_request_event.set()
+            return DisconnectRequestResult(
+                status="unavailable",
+                reason="channels_not_connected",
+            )
+        self._disconnect_request_sent_interrupt_count = len(self._sent_interrupt_reports)
+        self._events.append("request_disconnect")
+        self._disconnect_request_event.set()
+        if self._disconnect_request_auto_complete:
+            await self.complete_disconnect_request()
+        return DisconnectRequestResult(
+            status="requested",
+            channels=("control", "interrupt"),
+        )
+
+    async def list_bonded_peers(self) -> tuple[BondedPeer, ...]:
+        """Return the fake current reconnect candidate configured by a test."""
+        self._require_open()
+        if len(self._bonded_peer_addresses) > 1:
+            msg = "fake transport contains multiple current reconnect candidates"
+            raise InvalidKeyStoreError(msg)
+        return tuple(BondedPeer(address=address) for address in self._bonded_peer_addresses)
+
+    async def connect_bonded_peer(
+        self,
+        peer_address: str,
+        *,
+        connect_timeout: float | None,
+    ) -> None:
+        """Record an active reconnect attempt to a fake bonded peer."""
+        _ = connect_timeout
+        self._require_open()
+        if peer_address not in self._bonded_peer_addresses:
+            msg = f"unknown bonded peer: {peer_address}"
+            raise ValueError(msg)
+        self._events.append("active_reconnect")
+        if self._active_reconnect_error is not None:
+            raise self._active_reconnect_error
+        if self._active_reconnect_auto_connect:
+            await self.connect()
+
+    async def wait_for_disconnect_request(self, *, max_wait: float = 0.5) -> None:
+        """Wait until a fake remote disconnect request has been recorded."""
+        async with asyncio.timeout(max_wait):
+            await self._disconnect_request_event.wait()
+
+    async def wait_for_close_start(self, *, max_wait: float = 0.5) -> None:
+        """Wait until fake transport close has started."""
+        async with asyncio.timeout(max_wait):
+            await self._close_start_event.wait()
+
+    async def complete_disconnect_request(self, reason: int | None = None) -> None:
+        """Emit the host-side close completion for a pending fake request."""
+        if not self._control_channel_open and not self._interrupt_channel_open:
+            return
+        self._require_open()
+        self._control_channel_open = False
+        self._interrupt_channel_open = False
+        self._connected_emitted = False
+        self._events.append("disconnect_request_closed")
+        if self._disconnected_callback is not None:
+            await self._disconnected_callback(reason)
+
+    async def connect(self) -> None:
+        """Emit a fake host connection event."""
+        self._require_open()
+        self._control_channel_open = True
+        self._interrupt_channel_open = True
+        await self._emit_connected_once()
+
+    async def open_l2cap_channel(self, channel: Literal["control", "interrupt"]) -> None:
+        """Emit one fake L2CAP channel-open event."""
+        self._require_open()
+        if channel == "control":
+            self._control_channel_open = True
+            self._events.append("l2cap_control_open")
+        else:
+            self._interrupt_channel_open = True
+            self._events.append("l2cap_interrupt_open")
+        await self._emit_connected_once()
+
+    async def disconnect(self, reason: int | None = None) -> None:
+        """Emit a fake host disconnection event."""
+        self._require_open()
+        self._control_channel_open = False
+        self._interrupt_channel_open = False
+        self._connected_emitted = False
+        self._events.append("disconnected")
+        if self._disconnected_callback is not None:
+            await self._disconnected_callback(reason)
+
+    async def inject_interrupt_data(self, payload: bytes) -> None:
+        """Inject host-to-device data into the registered interrupt callback."""
+        self._require_open()
+        self._events.append("interrupt_rx")
+        if self._interrupt_callback is not None:
+            await self._interrupt_callback(bytes(payload))
+
+    async def inject_control_data(self, payload: bytes) -> None:
+        """Inject host-to-device data into the registered control callback."""
+        self._require_open()
+        self._events.append("control_rx")
+        if self._control_callback is not None:
+            await self._control_callback(bytes(payload))
+
+    async def send_interrupt(self, payload: bytes) -> None:
+        """Record an interrupt report."""
+        self._require_open()
+        if self._send_interrupt_error is not None:
+            raise self._send_interrupt_error
+        self._sent_interrupt_reports.append(bytes(payload))
+        self._interrupt_report_event.set()
+
+    async def wait_for_interrupt_report_count(
+        self,
+        count: int,
+        *,
+        max_wait: float = 0.5,
+    ) -> tuple[bytes, ...]:
+        """Wait until at least count interrupt reports have been recorded."""
+        async with asyncio.timeout(max_wait):
+            while len(self._sent_interrupt_reports) < count:
+                self._interrupt_report_event.clear()
+                if len(self._sent_interrupt_reports) >= count:
+                    break
+                await self._interrupt_report_event.wait()
+        return self.sent_interrupt_reports
+
+    async def wait_for_interrupt_report_id(
+        self,
+        report_id: int,
+        *,
+        max_wait: float = 0.5,
+    ) -> bytes:
+        """Wait until an interrupt report with report_id has been recorded."""
+        async with asyncio.timeout(max_wait):
+            while True:
+                for report in self._sent_interrupt_reports:
+                    if report and report[0] == report_id:
+                        return report
+                self._interrupt_report_event.clear()
+                await self._interrupt_report_event.wait()
+
+    async def send_control(self, payload: bytes) -> None:
+        """Record a control report."""
+        self._require_open()
+        self._sent_control_reports.append(bytes(payload))
+
+    def on_interrupt_data(self, callback: InterruptDataCallback) -> None:
+        """Register an interrupt data callback."""
+        self._interrupt_callback = callback
+
+    def on_control_data(self, callback: ControlDataCallback) -> None:
+        """Register a control data callback."""
+        self._control_callback = callback
+
+    def on_connected(self, callback: ConnectedCallback) -> None:
+        """Register a connection callback."""
+        self._connected_callback = callback
+
+    def on_disconnected(self, callback: DisconnectedCallback) -> None:
+        """Register a disconnection callback."""
+        self._disconnected_callback = callback
+
+    def _require_open(self) -> None:
+        if not self._is_open:
+            msg = "fake transport is not open"
+            raise ClosedError(msg)
+
+    async def _emit_connected_once(self) -> None:
+        if (
+            self._connected_emitted
+            or not self._control_channel_open
+            or not self._interrupt_channel_open
+        ):
+            return
+        self._connected_emitted = True
+        self._events.append("connected")
+        if self._connected_callback is not None:
+            await self._connected_callback()

swbt_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: swbt-python
+Version: 0.1.0
+Summary: Python library for presenting an NX-compatible virtual Bluetooth HID input device.
+Keywords: bluetooth,bluetooth-hid,controller,gamepad,hid,nx
+Author: niart120
+Author-email: niart120 <38847256+niart120@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: bumble>=0.0.230,<0.0.231
+Maintainer: niart120
+Maintainer-email: niart120 <38847256+niart120@users.noreply.github.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# swbt-python
+
+NX 向けの仮想 Bluetooth HID 入力デバイスを Python から扱うためのライブラリです。
+
+本ライブラリは pre-alpha 版です。実機での動作は Bluetooth adapter、driver、対象機器の firmware に依存します。
+
+## 必要なもの
+
+- Python 3.12 以降
+- uv
+- Bumble が利用可能な専用 USB Bluetooth dongle
+
+## インストール
+
+```powershell
+pip install swbt-python
+```
+
+ソースから動かす場合は次を使います。
+
+```powershell
+uv sync --dev
+```
+
+## ドキュメント
+
+[公開ドキュメント](https://niart120.github.io/swbt-python/) には API、利用例、実機準備、AI エージェント向け要約があります。
+
+- API 仕様: [API Reference](https://niart120.github.io/swbt-python/api/)
+- 利用例: [Usage Guide](https://niart120.github.io/swbt-python/usage/)
+- 実機構成と troubleshooting: [Hardware Guide](https://niart120.github.io/swbt-python/hardware/)
+- AI エージェント向け要約: [Agent Brief](https://niart120.github.io/swbt-python/agent-brief/)
+
+リポジトリを checkout している場合、同じ内容は `docs/` 配下でも確認できます。
+
+## 利用例
+
+```python
+import asyncio
+from swbt import Button, SwitchGamepad
+
+
+async def main() -> None:
+    async with SwitchGamepad(
+        adapter="usb:0",
+        key_store_path="switch-bond.json",
+    ) as pad:
+        await pad.connect(
+            timeout=30.0,
+            allow_pairing=True,
+        )
+        await pad.tap(Button.A)
+        await pad.neutral()
+
+
+asyncio.run(main())
+```
+
+この例は専用 Bluetooth adapter を使い、HID advertising、pairing または reconnect、periodic report loop、入力送信を行います。専用 USB Bluetooth dongle と接続情報のファイルパスを指定し、終了時は neutral を送ってから接続を閉じます。
+
+接続方法、`key_store_path`、入力 API の使い分けは [Usage Guide](https://niart120.github.io/swbt-python/usage/) にあります。
+
+## 実機検証
+
+実機接続には、PC の通常 Bluetooth 機能と共有しない専用 USB Bluetooth dongle と、OS ごとの driver 準備が必要です。Windows では、[Zadig](https://zadig.akeo.ie/) などで専用 dongle に WinUSB / libwdi driver を入れてから adapter 名を確認します。
+
+driver 準備、adapter 名の確認、troubleshooting は [Hardware Guide](https://niart120.github.io/swbt-python/hardware/) にあります。実機ログの正本は [hardware-test-log](https://niart120.github.io/swbt-python/hardware-test-log/) です。
+
+### 確認済み構成
+
+2026-07-04 時点では、Windows 11 / CSR8510 A10 / WinUSB / Switch 2 firmware 22.1.0 で、pairing、reconnect、Button A、D-pad、left / right stick、neutral 後の入力残りなしを確認済みです。adapter 名の例は `usb:0` です。
+
+### 試験的構成
+
+Linux / macOS は experimental です。手順は Hardware Guide に整備されていますが、動作検証されていないことに留意してください。adapter が開けるか、pairing できるか、入力が反映されるかは未確認です。
+
+CSR8510 A10 以外の Bluetooth dongle、Switch 2 firmware 22.1.0 以外の対象機器は確認済み構成に含めていません。
+
+## 開発
+
+```powershell
+uv sync --dev
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check --no-progress
+uv run pytest tests/unit
+uv run pytest tests/integration
+```
+
+## ライセンス
+
+MIT ライセンスです。全文は [LICENSE](https://github.com/niart120/swbt-python/blob/main/LICENSE) にあります。
+
+## 注記
+
+このプロジェクトは、対象機器や関連商標の権利者から承認、後援、提携を受けたものではありません。

swbt_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+swbt/__init__.py,sha256=PuZgNf9fGz3pj6M4n6UJk3FmJBCZ_7ScVS2yH7cGvR4,977
+swbt/diagnostics.py,sha256=vEdPBA82D-de7KpJZ3uc6nGQJHTxCx2LJrWKYfaYF-M,6839
+swbt/errors.py,sha256=4GESTg-mBGYMHPpyiZ9FtcZGDOXH5nkFV8q0bT-MylY,848
+swbt/gamepad/__init__.py,sha256=2lbuvAZd7L5nErkQyaoDIF5TaSDgX_HdAxMX2j7nzmY,362
+swbt/gamepad/connection.py,sha256=eqQ2CIcbhJaT9UpAtqOKsdwObQoPlRrfBwvBJcSboSI,7477
+swbt/gamepad/core.py,sha256=BeAGQWkoE9fMnLoulnrENyYB3iYF5v81kHm6Lw6kFAU,26994
+swbt/gamepad/output.py,sha256=2L1yWjGGgEfG4rhc2q2tlKVW9Q6r5K_tg6NmjbMkgy4,2805
+swbt/gamepad/transport_factory.py,sha256=ezw0Xa-zTcFZneFOF6uFlZJG8JSmyzQWbnJA0dFnLnY,666
+swbt/input.py,sha256=wQdyNqlzv8yi95damb9eGE-sR0VHFMqRqVdUdG_Cwoo,17427
+swbt/probe.py,sha256=E-N84PKrENvT7pm8ZxGe_Er5kHOievDimqC4O0GqXXY,4479
+swbt/protocol/__init__.py,sha256=Uvdlp06CBsKDivW1juPY-T5LaqJVCF00MbQaHl13XPo,35
+swbt/protocol/input_report.py,sha256=bXUFr7B0RWyFAxZXOs4D5ekOdDSm8q_H2F_V86KHJDY,2459
+swbt/protocol/output_report.py,sha256=00d-QZRBWFJ9k5ZLl5I0nSAe2pZY0oR50Z0YvZ2_YWs,1751
+swbt/protocol/profile.py,sha256=sIjRDrD3kvIiCNfbrc_5cuzTSiffrXg9cEp_l_qkYKQ,3340
+swbt/protocol/rumble.py,sha256=94Qq4gstmU5KlER-i0eW3mSr1HKY3CgArdz9D5gpqso,584
+swbt/protocol/spi.py,sha256=zBXti5vyZ0b5_cw_m_xGEWuxt-iTYejfX0D-PV9nR_E,1347
+swbt/protocol/subcommand.py,sha256=STXPKN1sCYSxvVtykuvO_PMBjX6OdMrPcBol07N3v1M,3825
+swbt/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+swbt/report_loop.py,sha256=W9cEZjs7VHpIyJ1WZwwmDeGWGiiJN4IE4ksEIhNgjps,4422
+swbt/state_store.py,sha256=06niyjEJ9Z9ht3aJCSCvhe5R2dCmKCKuoKFafBp-JyE,2172
+swbt/transport/__init__.py,sha256=b_Vqsg0k_g7XclN9XHQrcJxqCwGIklxG5NqzISal4_I,68
+swbt/transport/_bumble_acl.py,sha256=RnueTwEgAd0w3YgxnXkw0AKQXMeECIRope96W-xQ1K8,1425
+swbt/transport/_bumble_hidp.py,sha256=mL_eT-otopHzg5G0p7uhqTYsqSuDwdXAiAwakQiHbCY,835
+swbt/transport/_bumble_key_store.py,sha256=r8rFJ1QvhnBwczEnFABE2z66YFkXU_aEu64ihHec96s,7605
+swbt/transport/_bumble_lifecycle.py,sha256=DHEMbZOfRLHD9jF62c2zLAn-TuFLk-8WzE1OdTSxoKI,11187
+swbt/transport/_bumble_sdp.py,sha256=swD9yhqrgjqOOpT0-rgBdtiFX1VmKjS3A6TWPu6mV0k,8132
+swbt/transport/base.py,sha256=wv3HOhv8CDWbX0T8f687DtH01gh8TW4gsCWwIi5tKH4,2885
+swbt/transport/bumble.py,sha256=6tzI4Pn3W1ndsbAo5LO7-7v7MfU8N2pRHeOLIvkoo4Q,27524
+swbt/transport/fake.py,sha256=Y5gTiOrmldkxp0xdG5SxYgTXpeLW8pRRRvb3F7HL9qE,12542
+swbt_python-0.1.0.dist-info/licenses/LICENSE,sha256=FzzUoYjuIh5DzpeaujIbDUTylYnyzcHRVU-_ZMyowyk,1065
+swbt_python-0.1.0.dist-info/WHEEL,sha256=uOqnPWqgFlbov4NeTCercq7cBQ2UN7xh5fiW55lOnAg,81
+swbt_python-0.1.0.dist-info/entry_points.txt,sha256=YYQc7VgoSy74iZ6s8Qr6iJpnvFoDpp8G4-v0KJH5TGo,48
+swbt_python-0.1.0.dist-info/METADATA,sha256=P4iKDIXfy6Xi6Ol_HRHF_w5AHpbyKzfmzR9-bXaUbTw,4811
+swbt_python-0.1.0.dist-info/RECORD,,

swbt_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.26
+Root-Is-Purelib: true
+Tag: py3-none-any

swbt_python-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+swbt-probe = swbt.probe:main
+

swbt_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 niart120
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.