Bluetooth Auto Recovery

Common errors

• Failed to connect to Bluetooth management socket: [Errno 13] Permission denied

  cause The Python script does not have sufficient permissions to access the Bluetooth management socket (e.g., `/var/run/bluetooth/mgmt`).
  fix Run the Python script with `sudo` (e.g., `sudo python your_script.py`) or adjust user permissions to allow access to the Bluetooth management socket and `rfkill`.

• ModuleNotFoundError: No module named 'dbus_next'

  cause The `dbus-next` dependency, which is crucial for D-Bus communication, is not installed.
  fix Install the required dependency: `pip install bluetooth-auto-recovery` (which should pull `dbus-next`) or explicitly `pip install dbus-next`.

• RuntimeError: Event loop is already running

  cause Attempting to run `asyncio.run()` when an `asyncio` event loop is already active in the current thread, or calling async functions outside of an awaitable context.
  fix Ensure `asyncio.run()` is called only once as the top-level entry point for your asynchronous code, typically within `if __name__ == '__main__':`. If integrating into an existing async application, use `asyncio.create_task()` or `await` directly within the existing event loop.

Warnings

• gotcha This library relies on Linux-specific Bluetooth management sockets (BlueZ) and typically requires root or `sudo` privileges to operate correctly. Running without elevated permissions will likely result in permission errors or inability to access Bluetooth hardware.
  Fix: Run your Python script with `sudo python your_script.py` or ensure the user running the script has appropriate permissions to access `/var/run/bluetooth/mgmt` and interact with `rfkill`.
• gotcha The library depends on a specific, potentially patched version of `pybluez` fetched directly from GitHub via its `pyproject.toml`. While `pip` generally handles this, custom `pybluez` installations or conflicts with system-installed `pybluez` might occur, especially in isolated environments.
  Fix: Ensure `pip` is able to fetch and install git dependencies. If issues arise, consider creating a clean virtual environment or checking the GitHub repository for the exact `pybluez` fork used.
• gotcha The `BluetoothAutoRecovery` class is designed for asynchronous operations and must be run within an `asyncio` event loop. Improper use outside an async context or incorrect handling of the event loop can lead to `RuntimeError` or unexpected behavior.
  Fix: Always use `async with BluetoothAutoRecovery(...)` and ensure your application's entry point uses `asyncio.run(main_async_function())` to correctly manage the event loop.
• gotcha For containerized environments (e.g., Docker), the Bluetooth management socket path might be different or require specific volume mounts. The default path is `/var/run/bluetooth/mgmt`.
  Fix: If running in a container, verify the correct path to the Bluetooth management socket within the container and pass it to the `bluetooth_management_socket` parameter of `BluetoothAutoRecovery`.

Install

• pip install bluetooth-auto-recovery Install latest version

Imports

• BluetoothAutoRecovery

  from bluetooth_auto_recovery import BluetoothAutoRecovery

Quickstart

Initializes `BluetoothAutoRecovery` and starts monitoring Bluetooth adapters in an asynchronous context. The recovery process runs in the background, attempting to fix unresponsive adapters. This example includes a robust shutdown on `KeyboardInterrupt`.

import asyncio
from bluetooth_auto_recovery import BluetoothAutoRecovery

async def main():
    print("Starting Bluetooth Auto Recovery...")
    async with BluetoothAutoRecovery(
        recovery_timeout=60, # Max time to wait for recovery in seconds
        unresponsive_timeout=300 # Time to wait for unresponsiveness before recovering
    ) as recovery:
        print("Monitoring Bluetooth adapters. Press Ctrl+C to stop.")
        try:
            # Start monitoring in the background
            await recovery.start()
            # Keep the main task running indefinitely to monitor
            await asyncio.Future() # Await an eternal future
        except asyncio.CancelledError:
            print("Monitoring stopped.")
        finally:
            await recovery.stop() # Explicitly stop the recovery
            print("Bluetooth Auto Recovery stopped.")

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Program interrupted by user.")