{"id":8813,"library":"aioblescan","title":"Bluetooth LE Scanner with Asyncio","description":"aioblescan is a Python library that allows for scanning Bluetooth Low Energy (BLE) advertised information using `asyncio`. It enables developers to build asynchronous applications that interact with BLE devices, decoding various advertising packet types. The current version is 0.2.14, with releases occurring periodically to add new plugin support and fix issues.","status":"active","version":"0.2.14","language":"en","source_language":"en","source_url":"http://github.com/frawau/aioblescan","tags":["bluetooth","ble","asyncio","scanner","iot","low-energy"],"install":[{"cmd":"pip install aioblescan","lang":"bash","label":"Install stable version"},{"cmd":"pip install git+https://github.com/frawau/aioblescan.git","lang":"bash","label":"Install from GitHub (latest dev)"}],"dependencies":[],"imports":[{"note":"BLEScanner is located within the 'scanner' submodule, not directly under 'aioblescan'.","wrong":"from aioblescan import BLEScanner","symbol":"BLEScanner","correct":"from aioblescan.scanner import BLEScanner"},{"note":"Plugins like Eddystone are located in the 'plugins' submodule.","symbol":"Eddystone","correct":"from aioblescan.plugins import Eddystone"},{"note":"The HCITransport class is found in the 'hcitool' submodule.","symbol":"HCITransport","correct":"from aioblescan.hcitool import HCITransport"}],"quickstart":{"code":"import asyncio\nfrom aioblescan.scanner import BLEScanner\nfrom aioblescan.plugins import Eddystone\n\nasync def main():\n    scanner = BLEScanner()\n    eddystone = Eddystone()\n\n    def my_detection_callback(data):\n        try:\n            ev = eddystone.decode(data)\n            if ev:\n                print(f\"Detected Eddystone: {ev}\")\n        except Exception as e:\n            print(f\"Error decoding packet: {e}\")\n\n    scanner.register_plugin(eddystone)\n    scanner.process_data = my_detection_callback # Direct callback for all processed data\n\n    await scanner.start()\n    print(\"BLE scanning started... Press Ctrl+C to stop.\")\n    try:\n        await asyncio.Event().wait() # Keep the main task running indefinitely\n    except asyncio.CancelledError:\n        pass\n    finally:\n        await scanner.stop()\n        print(\"BLE scanning stopped.\")\n\nif __name__ == \"__main__\":\n    try:\n        asyncio.run(main())\n    except KeyboardInterrupt:\n        print(\"Exiting.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Run 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)`.","message":"aioblescan 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"The 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.","severity":"breaking","affected_versions":"0.2.14 and later"},{"fix":"Add checks like `if ev:` after calling `plugin.decode(data)` to ensure you only process successfully decoded events.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run the script with `sudo python3 your_script.py` or grant the Python interpreter `cap_net_raw` and `cap_net_admin` capabilities using `sudo setcap 'cap_net_raw,cap_net_admin+eip' $(which python3)`.","cause":"The script does not have sufficient permissions to access the Bluetooth HCI device.","error":"aioblescan.hcitool.HCI_Exception: Cannot open Bluetooth device socket"},{"fix":"Change your import statement to `from aioblescan.scanner import BLEScanner`.","cause":"Incorrect import path. You might be trying to import `BLEScanner` directly from `aioblescan`.","error":"ModuleNotFoundError: No module named 'aioblescan.scanner'"},{"fix":"Ensure you assign a valid function or lambda to `scanner.process_data = your_callback_function`.","cause":"The `process_data` attribute of `BLEScanner` is expected to be a function or method that processes detected data. This error occurs if you assign a non-callable object.","error":"TypeError: BLEScanner.process_data expected a callable or None, got <something_else>"}]}