Registry / devops / bluetooth-auto-recovery

bluetooth-auto-recovery

JSON →
library1.6.4pypypi✓ verified 87d ago

bluetooth-auto-recovery is a Python library designed to detect and recover Bluetooth adapters that enter an unresponsive or 'stuck' state. It actively monitors Bluetooth management sockets and initiates recovery procedures, such as resetting the adapter, when issues are detected. The current version is 1.5.3, with minor releases focusing on bug fixes and dependency updates, typically every few months.

pip install bluetooth-auto-recovery
INSTALL
IMPORT
SIG · BLUETOOTH-AUTO-REC
B
bluetooth-auto-recovery
devopspythonv1.6.4
Install
3.7s avg
Import
—
Disk
24MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.6.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 26.6MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 3.7s · import 0.000s · 27MB
24MB installed
● package 24MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

recover_adapter
✓ from bluetooth_auto_recovery import recover_adapter
✗ from bluetooth_auto_recovery import BluetoothAutoRecovery

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.")
Debug
Known issues
gotchaThis 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`.
affects: All versions
gotchaThe 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.
affects: All versions
gotchaThe `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.
affects: All versions
gotchaFor 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`.
affects: All versions
Upgrade
Version history
1.6.4latest on PyPI · released May 25, 2026
Audit
Dependencies
dbus-nextrequiredRequired for D-Bus communication with the system's Bluetooth daemon (BlueZ).
Agent activity
19 hits · last 30 days
node
18
OpenAI (training)
1
Resources
bluetooth-auto-recovery — pip install bluetooth-auto-recovery · libregistry