Bleak support

docs/async_migration.md

@@ -0,0 +1,48 @@
+# Async Nxbt Migration Notes
+
+## Overview
+
+NXBT now exposes an async-friendly facade so that applications can await controller
+lifecycle events directly instead of relying on background threads. The new
+`nxbt.AsyncNxbtClient` wraps the legacy `Nxbt` API but offloads each blocking call
+to a worker thread, allowing you to coordinate controllers from within an
+`asyncio` event loop.
+
+```python
+import asyncio
+from nxbt import AsyncNxbtClient, PRO_CONTROLLER
+
+
+async def main():
+    async with AsyncNxbtClient(debug=False) as nx:
+        adapters = await nx.get_available_adapters()
+        index = await nx.create_controller(PRO_CONTROLLER, adapters[0])
+        await nx.wait_for_connection(index)
+        await nx.macro(index, "A 0.1s\n0.1s")
+
+asyncio.run(main())
+```
+
+Key points:
+
+1. Use `async with AsyncNxbtClient(...)` to ensure cleanup mirrors the previous
+   `atexit` behaviour (BlueZ toggles, runtime shutdown).
+2. All high-level helpers (`macro`, `press_buttons`, `tilt_stick`, `set_controller_input`,
+   `wait_for_connection`, etc.) are now `await`-able. The `state` dict remains
+   synchronous for quick inspection without additional locking.
+3. CLI utilities (`nxbt.cli` commands and `scripts/demo_loop.py`) already route
+   through `asyncio.run`, so they can be embedded inside larger event loops or
+   scripted via `asyncio.create_task`.
+
+### Compatibility
+
+The legacy `Nxbt` class still works for synchronous consumers and continues to
+wrap the async controller manager internally. Downstream callers can migrate at
+their own pace:
+
+- **Synchronous projects** – keep using `Nxbt` as before.
+- **Async-aware projects** – switch to `AsyncNxbtClient` and await controller
+  operations directly.
+
+Future releases will update the TUI and web entry points to the async client as
+well, completing Phase 4 of the refactor plan.

docs/async_refactor_plan.md

@@ -0,0 +1,37 @@
+# NXBT Async Refactor Plan (Checklist)
+
+## Phase 1 – Adapter & Utilities
+- [x] Build a first-class `AsyncBleakAdapter` mirroring Bleak’s async API surface (scanner contexts, client connect/disconnect, GATT helpers).
+- [x] Provide thin, clearly marked synchronous shims for legacy imports (current `BlueZ` now wraps `AsyncBleakAdapter`).
+- [x] Audit helper functions (`find_objects`, `find_devices_by_alias`, discovery utilities) and offer async primitives with safe sync wrappers (`asyncio.run`).
+- [ ] Validate helpers with demo scripts (`scripts/testbt.py`, `scanner.py`) across supported OSes.
+
+## Phase 2 – Controller & Bluetooth Stack
+- [x] Convert controller modules (`controller.py`, `server.py`, protocol helpers) to async functions end-to-end. (`AsyncController` and `ControllerServer` now run entirely via asyncio, with sync shims retained for backwards compatibility.)
+- [x] Introduce an `AsyncController` and ensure `ControllerServer` consumes it for setup.
+- [x] Add an `AsyncControllerServer` facade so higher layers can await controller lifecycles.
+- [x] Expose `run_async`/`connect_async`/`reconnect_async`/`mainloop_async` wrappers (no more thread offloading) to unblock higher-level async orchestration.
+- [x] Replace blocking socket/BLE operations with `asyncio` sockets/tasks and cancellation-friendly loops (connect, reconnect, and mainloop now awaitable).
+- [x] Document SDP/profile limitations: Bleak does not expose cross-platform profile registration, so `AsyncController` logs a warning and Phase 4 docs will direct Linux users to BlueZ if they need SDP features.
+
+## Phase 3 – Core Nxbt Process & IPC
+- [x] Introduce an `AsyncNxbt` manager that spawns controller servers as asyncio tasks (`nxbt/async_nxbt.py`).
+- [x] Provide a bridge in `Nxbt` (`use_async=True`) that routes controller creation, macro queues, and state tracking through the async manager.
+- [x] Replace the legacy multiprocessing `Nxbt` manager entirely (or make async the default) so controllers run as tasks inside a single event loop.
+- [x] Replace multiprocessing Queue/Lock coordination with `asyncio.Queue`, `asyncio.Lock`, or `TaskGroup` equivalents.
+- [x] Ensure graceful shutdown awaits outstanding tasks and closes BLE clients cleanly in both modes.
+
+## Phase 4 – CLI, Scripts, and External APIs
+- [ ] Update CLI commands, demo scripts, and web/tui entry points to drive the async core (wrap in `asyncio.run`).
+    - [x] CLI macros/test/demo and `scripts/demo_loop.py` now run under `asyncio` via `AsyncNxbtClient`.
+    - [x] Web app entry point now routes through a shared `AsyncNxbtClientBridge`.
+    - [x] `tui.py` uses the async bridge for controller management/input updates.
+- [x] Revise public APIs in `nxbt/__init__.py` to expose async entry points (or clearly documented sync wrappers).
+- [x] Provide migration notes guiding downstream users on awaiting the new APIs.
+- [ ] Exercise async CLI/demo/TUI flows on real BLE hardware to catch regressions (blocked on hardware availability).
+
+## Phase 5 – Testing, Tooling, and Documentation
+- [ ] Add async-aware tests (e.g., `pytest-asyncio`) covering discovery, controller lifecycles, and failure scenarios.
+- [ ] Integrate async tests into CI with BLE-aware skips/mocks where hardware is unavailable.
+- [ ] Update README/docs to emphasize the async model, environment requirements, and Bleak-based examples.
+- [ ] Final cleanup: remove obsolete BlueZ-only utilities, ensure lint/type tools understand async interfaces, and tag a release with migration guidance.