BleakScanner class

class bleak.BleakScanner(detection_callback: Optional[AdvertisementDataCallback] = None, service_uuids: Optional[List[str]] = None, scanning_mode: Literal['active', 'passive'] = 'active', *, bluez: BlueZScannerArgs = {}, cb: CBScannerArgs = {}, backend: Optional[Type[BaseBleakScanner]] = None, **kwargs)[source]

Interface for Bleak Bluetooth LE Scanners.

The scanner will listen for BLE advertisements, optionally filtering on advertised services or other conditions, and collect a list of BLEDevice objects. These can subsequently be used to connect to the corresponding BLE server.

A BleakScanner can be used as an asynchronous context manager in which case it automatically starts and stops scanning.

Parameters
  • detection_callback – Optional function that will be called each time a device is discovered or advertising data has changed.

  • service_uuids – Optional list of service UUIDs to filter on. Only advertisements containing this advertising data will be received. Required on macOS >= 12.0, < 12.3 (unless you create an app with py2app).

  • scanning_mode – Set to "passive" to avoid the "active" scanning mode. Passive scanning is not supported on macOS! Will raise BleakError if set to "passive" on macOS.

  • bluez – Dictionary of arguments specific to the BlueZ backend.

  • cb – Dictionary of arguments specific to the CoreBluetooth backend.

  • backend – Used to override the automatically selected backend (i.e. for a custom backend).

  • **kwargs – Additional args for backwards compatibility.

Changed in version 0.15.0: detection_callback, service_uuids and scanning_mode are no longer keyword-only. Added bluez parameter.

Changed in version 0.18.0: No longer is alias for backend type and no longer inherits from BaseBleakScanner. Added backend parameter.

Easy methods

These methods and handy for simple programs but are not recommended for more advanced use cases like long running programs, GUIs or connecting to multiple devices.

async classmethod BleakScanner.discover(timeout: float = 5.0, *, return_adv: Literal[False] = False, **kwargs) List[BLEDevice][source]
async classmethod BleakScanner.discover(timeout: float = 5.0, *, return_adv: Literal[True], **kwargs) Dict[str, Tuple[BLEDevice, AdvertisementData]]

Scan continuously for timeout seconds and return discovered devices.

Parameters
  • timeout – Time, in seconds, to scan for.

  • return_adv – If True, the return value will include advertising data.

  • **kwargs – Additional arguments will be passed to the BleakScanner constructor.

Returns

The value of discovered_devices_and_advertisement_data if return_adv is True, otherwise the value of discovered_devices.

Changed in version 0.19.0: Added return_adv parameter.

async classmethod BleakScanner.find_device_by_name(name: str, timeout: float = 10.0, **kwargs) Optional[BLEDevice][source]

Obtain a BLEDevice for a BLE server specified by the local name in the advertising data.

Parameters
  • name – The name sought.

  • timeout – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

  • **kwargs – additional args passed to the BleakScanner constructor.

Returns

The BLEDevice sought or None if not detected.

async classmethod BleakScanner.find_device_by_address(device_identifier: str, timeout: float = 10.0, **kwargs) Optional[BLEDevice][source]

Obtain a BLEDevice for a BLE server specified by Bluetooth address or (macOS) UUID address.

Parameters
  • device_identifier – The Bluetooth/UUID address of the Bluetooth peripheral sought.

  • timeout – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

  • **kwargs – additional args passed to the BleakScanner constructor.

Returns

The BLEDevice sought or None if not detected.

async classmethod BleakScanner.find_device_by_filter(filterfunc: Callable[[BLEDevice, AdvertisementData], bool], timeout: float = 10.0, **kwargs) Optional[BLEDevice][source]

Obtain a BLEDevice for a BLE server that matches a given filter function.

This can be used to find a BLE server by other identifying information than its address, for example its name.

Parameters
  • filterfunc – A function that is called for every BLEDevice found. It should return True only for the wanted device.

  • timeout – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

  • **kwargs – Additional arguments to be passed to the BleakScanner constructor.

Returns

The BLEDevice sought or None if not detected before the timeout.

Starting and stopping

BleakScanner is an context manager so the recommended way to start and stop scanning is to use it in an async with statement:

import asyncio
from bleak import BleakScanner

async def main():
    stop_event = asyncio.Event()

    # TODO: add something that calls stop_event.set()

    def callback(device, advertising_data):
        # TODO: do something with incoming data
        pass

    async with BleakScanner(callback) as scanner:
        ...
        # Important! Wait for an event to trigger stop, otherwise scanner
        # will stop immediately.
        await stop_event.wait()

    # scanner stops when block exits
    ...

asyncio.run(main())

It can also be started and stopped without using the context manager using the following methods:

async BleakScanner.start()[source]

Start scanning for devices

async BleakScanner.stop()[source]

Stop scanning for devices

Getting discovered devices and advertisement data

If you aren’t using the “easy” class methods, there are two ways to get the discovered devices and advertisement data.

For event-driven programming, you can provide a detection_callback callback to the BleakScanner constructor. This will be called back each time and advertisement is received.

Otherwise, you can use one of the properties below after scanning has stopped.

property BleakScanner.discovered_devices: List[BLEDevice]

Gets list of the devices that the scanner has discovered during the scanning.

If you also need advertisement data, use discovered_devices_and_advertisement_data instead.

property BleakScanner.discovered_devices_and_advertisement_data: Dict[str, Tuple[BLEDevice, AdvertisementData]]

Gets a map of device address to tuples of devices and the most recently received advertisement data for that device.

The address keys are useful to compare the discovered devices to a set of known devices. If you don’t need to do that, consider using discovered_devices_and_advertisement_data.values() to just get the values instead.

New in version 0.19.0.

Deprecated

BleakScanner.register_detection_callback(callback: Optional[Callable[[BLEDevice, AdvertisementData], Optional[Awaitable[None]]]]) None[source]

Register a callback that is called when a device is discovered or has a property changed.

Deprecated since version 0.17.0: This method will be removed in a future version of Bleak. Pass the callback directly to the BleakScanner constructor instead.

Parameters

callback – A function, coroutine or None.

BleakScanner.set_scanning_filter(**kwargs)[source]

Set scanning filter for the BleakScanner.

Deprecated since version 0.17.0: This method will be removed in a future version of Bleak. Pass arguments directly to the BleakScanner constructor instead.

Parameters

**kwargs – The filter details.

async BleakScanner.get_discovered_devices() List[BLEDevice][source]

Gets the devices registered by the BleakScanner.

Deprecated since version 0.11.0: This method will be removed in a future version of Bleak. Use the discovered_devices property instead.

Returns

A list of the devices that the scanner has discovered during the scanning.