48 lines
1.8 KiB
Markdown
48 lines
1.8 KiB
Markdown
# 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.
|