Install & Compatibility
Where this runs
tested against v0.2.14 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BLEScanRequester
✓ from aioblescan import BLEScanRequester
✗ from aioblescan.scanner import BLEScanner
This quickstart demonstrates how to initialize `BLEScanner` and register a plugin (Eddystone in this case) to decode specific advertisement types. It sets up a callback function to process detected data asynchronously and prints Eddystone frames. Remember to run this with root privileges or with appropriate capabilities (e.g., `sudo setcap 'cap_net_raw,cap_net_admin+eip' $(which python3)`) as Bluetooth HCI access typically requires elevated permissions.
import asyncio
from aioblescan.scanner import BLEScanner
from aioblescan.plugins import Eddystone
async def main():
scanner = BLEScanner()
eddystone = Eddystone()
def my_detection_callback(data):
try:
ev = eddystone.decode(data)
if ev:
print(f"Detected Eddystone: {ev}")
except Exception as e:
print(f"Error decoding packet: {e}")
scanner.register_plugin(eddystone)
scanner.process_data = my_detection_callback # Direct callback for all processed data
await scanner.start()
print("BLE scanning started... Press Ctrl+C to stop.")
try:
await asyncio.Event().wait() # Keep the main task running indefinitely
except asyncio.CancelledError:
pass
finally:
await scanner.stop()
print("BLE scanning stopped.")
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
print("Exiting.")
aioblescan --version
Debug
Known issues
gotchaaioblescan often requires elevated privileges (root or NET_RAW capabilities) to access the Bluetooth HCI device, especially on Linux systems. Running without these permissions will result in 'Permission denied' errors.fixRun your script with `sudo python3 your_script.py` or grant the Python executable the necessary capabilities: `sudo setcap 'cap_net_raw,cap_net_admin+eip' $(which python3)`.
affects: All versions
breakingThe console script support in version 0.2.14 and later explicitly targets Python 3.7 and up. While the library itself might still function on older Python 3 versions, the command-line utility for the Tilt plugin and other console scripts may not work correctly or be supported.fixEnsure you are using Python 3.7 or newer for console script functionality. For library usage, older Python 3 versions might work but are not officially tested or supported for this specific change.
affects: 0.2.14 and later
gotchaWhen processing advertisement data, ensure your callback handles `None` or empty results from plugin `decode` methods gracefully, as not all received packets will match a registered plugin's format.fixAdd checks like `if ev:` after calling `plugin.decode(data)` to ensure you only process successfully decoded events.
affects: All versions
Upgrade
Version history
0.2.14latest on PyPI · released Jan 7, 2023
Audit
Dependencies
No dependency data recorded yet.