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.