Bluetooth LE Scanner with Asyncio

0.2.14 · active · verified Thu Apr 16

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.

Common errors

```
aioblescan.hcitool.HCI_Exception: Cannot open Bluetooth device socket
```
cause The script does not have sufficient permissions to access the Bluetooth HCI device.

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)`.
```
ModuleNotFoundError: No module named 'aioblescan.scanner'
```
cause Incorrect import path. You might be trying to import `BLEScanner` directly from `aioblescan`.

fix Change your import statement to `from aioblescan.scanner import BLEScanner`.
```
TypeError: BLEScanner.process_data expected a callable or None, got <something_else>
```
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.

fix Ensure you assign a valid function or lambda to `scanner.process_data = your_callback_function`.

Warnings

gotcha 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.
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)`.
breaking 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.
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.
gotcha 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.
Fix: Add checks like `if ev:` after calling `plugin.decode(data)` to ensure you only process successfully decoded events.

Install

pip install aioblescan Install stable version
pip install git+https://github.com/frawau/aioblescan.git Install from GitHub (latest dev)

Imports

BLEScanner
wrong:
```
from aioblescan import BLEScanner
```
correct:
```
from aioblescan.scanner import BLEScanner
```
BLEScanner is located within the 'scanner' submodule, not directly under 'aioblescan'.
Eddystone
```
from aioblescan.plugins import Eddystone
```
Plugins like Eddystone are located in the 'plugins' submodule.
HCITransport
```
from aioblescan.hcitool import HCITransport
```
The HCITransport class is found in the 'hcitool' submodule.

Quickstart

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.")

view raw JSON →