nxbt/docs/async_refactor_plan.md

NXBT Async Refactor Plan (Checklist)

Phase 1 – Adapter & Utilities

• Build a first-class AsyncBleakAdapter mirroring Bleak’s async API surface (scanner contexts, client connect/disconnect, GATT helpers).
• Provide thin, clearly marked synchronous shims for legacy imports (current BlueZ now wraps AsyncBleakAdapter).
• 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

• 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.)
• Introduce an AsyncController and ensure ControllerServer consumes it for setup.
• Add an AsyncControllerServer facade so higher layers can await controller lifecycles.
• Expose run_async/connect_async/reconnect_async/mainloop_async wrappers (no more thread offloading) to unblock higher-level async orchestration.
• Replace blocking socket/BLE operations with asyncio sockets/tasks and cancellation-friendly loops (connect, reconnect, and mainloop now awaitable).
• 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

• Introduce an AsyncNxbt manager that spawns controller servers as asyncio tasks (nxbt/async_nxbt.py).
• Provide a bridge in Nxbt (use_async=True) that routes controller creation, macro queues, and state tracking through the async manager.
• Replace the legacy multiprocessing Nxbt manager entirely (or make async the default) so controllers run as tasks inside a single event loop.
• Replace multiprocessing Queue/Lock coordination with asyncio.Queue, asyncio.Lock, or TaskGroup equivalents.
• 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).
  • CLI macros/test/demo and scripts/demo_loop.py now run under asyncio via AsyncNxbtClient.
  • Web app entry point now routes through a shared AsyncNxbtClientBridge.
  • tui.py uses the async bridge for controller management/input updates.
• Revise public APIs in nxbt/__init__.py to expose async entry points (or clearly documented sync wrappers).
• 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.