nxbt/docs/async_migration.md

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.

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.