Interfaces, exceptions and utils

Connection Clients

Interface

Base class for backend clients.

Created on 2018-04-23 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.client.BaseBleakClient(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)[source]

The Client Interface for Bleak Backend implementations to implement.

The documentation of this interface should thus be safe to use as a reference for your implementation.

Parameters

address_or_ble_device (BLEDevice or str) – The Bluetooth address of the BLE peripheral to connect to or the BLEDevice object representing it.

Keyword Arguments

timeout (float) – Timeout for required discover call. Defaults to 10.0.
disconnected_callback (callable) – Callback that will be scheduled in the event loop when the client is disconnected. The callable must take one argument, which will be this client object.

abstract async connect(**kwargs) → bool[source]

Connect to the specified GATT server.

Returns: Boolean representing connection status.

abstract async disconnect() → bool[source]

Disconnect from the specified GATT server.

Returns: Boolean representing connection status.

abstract async get_services(**kwargs) → bleak.backends.service.BleakGATTServiceCollection[source]

Get all services registered for this GATT server.

Returns: A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

abstract property is_connected: bool

Check connection status between this client and the server.

Returns: Boolean representing connection status.

abstract async pair(*args, **kwargs) → bool[source]: Pair with the peripheral.

abstract async read_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], **kwargs) → bytearray[source]

Perform read operation on the specified GATT characteristic.

Parameters: char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
Returns: (bytearray) The read data.

abstract async read_gatt_descriptor(handle: int, **kwargs) → bytearray[source]

Perform read operation on the specified GATT descriptor.

Parameters: handle (int) – The handle of the descriptor to read from.
Returns: (bytearray) The read data.

set_disconnected_callback(callback: Optional[Callable[[bleak.backends.client.BaseBleakClient], None]], **kwargs) → None[source]

Set the disconnect callback. The callback will only be called on unsolicited disconnect event.

Callbacks must accept one input which is the client object itself.

Set the callback to None to remove any existing callback.

def callback(client):
    print("Client with address {} got disconnected!".format(client.address))

client.set_disconnected_callback(callback)
client.connect()

Parameters: callback – callback to be called on disconnection.

abstract async start_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None[source]

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be a integer handle of the characteristic generating the data and the second will be a bytearray.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)

Parameters

char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
callback (function) – The function to be called on notification.

abstract async stop_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID]) → None[source]

Deactivate notification/indication on a specified characteristic.

Parameters: char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

abstract async unpair() → bool[source]: Unpair with the peripheral.

abstract async write_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], data: Union[bytes, bytearray, memoryview], response: bool = False) → None[source]

Perform a write operation on the specified GATT characteristic.

Parameters

char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
data (bytes or bytearray) – The data to send.
response (bool) – If write-with-response operation should be done. Defaults to False.

abstract async write_gatt_descriptor(handle: int, data: Union[bytes, bytearray, memoryview]) → None[source]

Perform a write operation on the specified GATT descriptor.

Parameters

handle (int) – The handle of the descriptor to read from.
data (bytes or bytearray) – The data to send.

Windows

BLE Client for Windows 10 systems, implemented with WinRT.

Created on 2020-08-19 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.winrt.client.BleakClientWinRT(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], *, winrt: bleak.backends.winrt.client.WinRTClientArgs = {}, **kwargs)[source]

Native Windows Bleak Client.

Implemented using winrt, a package that enables Python developers to access Windows Runtime APIs directly from Python.

Parameters

address_or_ble_device (str or BLEDevice) – The Bluetooth address of the BLE peripheral to connect to or the BLEDevice object representing it.
winrt (dict) – A dictionary of Windows-specific configuration values.
**timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.
**disconnected_callback (callable) – Callback that will be scheduled in the event loop when the client is disconnected. The callable must take one argument, which will be this client object.

async connect(**kwargs) → bool[source]

Connect to the specified GATT server.

Keyword Arguments: timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.
Returns: Boolean representing connection status.

async disconnect() → bool[source]

Disconnect from the specified GATT server.

Returns: Boolean representing if device is disconnected.

async get_services(**kwargs) → bleak.backends.service.BleakGATTServiceCollection[source]

Get all services registered for this GATT server.

Returns: A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

property is_connected: bool

Check connection status between this client and the server.

Returns: Boolean representing connection status.

property mtu_size: int: Get ATT MTU size for active connection

async pair(protection_level: Optional[int] = None, **kwargs) → bool[source]

Attempts to pair with the device.

Keyword Arguments

protection_level (int) –

A DevicePairingProtectionLevel enum value:

None - Pair the device using no levels of protection.
Encryption - Pair the device using encryption.
EncryptionAndAuthentication - Pair the device using encryption and authentication. (This will not work in Bleak…)

Returns

Boolean regarding success of pairing.

async read_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], **kwargs) → bytearray[source]

Perform read operation on the specified GATT characteristic.

Parameters: char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
Keyword Arguments: use_cached (bool) – False forces Windows to read the value from the device again and not use its own cached value. Defaults to False.
Returns: (bytearray) The read data.

async read_gatt_descriptor(handle: int, **kwargs) → bytearray[source]

Perform read operation on the specified GATT descriptor.

Parameters: handle (int) – The handle of the descriptor to read from.
Keyword Arguments: use_cached (bool) – False forces Windows to read the value from the device again and not use its own cached value. Defaults to False.
Returns: (bytearray) The read data.

async start_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None[source]

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be a uuid string object and the second will be a bytearray.

def callback(sender, data):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)

Parameters

char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
callback (function) – The function to be called on notification.

Keyword Arguments

force_indicate (bool) – If this is set to True, then Bleak will set up a indication request instead of a notification request, given that the characteristic supports notifications as well as indications.

async stop_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID]) → None[source]

Deactivate notification/indication on a specified characteristic.

Parameters: char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

async unpair() → bool[source]

Attempts to unpair from the device.

N.B. unpairing also leads to disconnection in the Windows backend.

Returns: Boolean on whether the unparing was successful.

async write_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], data: Union[bytes, bytearray, memoryview], response: bool = False) → None[source]

Perform a write operation of the specified GATT characteristic.

Parameters

char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
data (bytes or bytearray) – The data to send.
response (bool) – If write-with-response operation should be done. Defaults to False.

async write_gatt_descriptor(handle: int, data: Union[bytes, bytearray, memoryview]) → None[source]

Perform a write operation on the specified GATT descriptor.

Parameters

handle (int) – The handle of the descriptor to read from.
data (bytes or bytearray) – The data to send.

class bleak.backends.winrt.client.WinRTClientArgs[source]

Windows-specific arguments for BleakClient.

address_type: Literal['public', 'random']: Can either be "public" or "random", depending on the required address type needed to connect to your device.

use_cached_services: bool

True allows Windows to fetch the services, characteristics and descriptors from the Windows cache instead of reading them from the device. Can be very much faster for known, unchanging devices, but not recommended for DIY peripherals where the GATT layout can change between connections.

False will force the attribute database to be read from the remote device instead of using the OS cache.

If omitted, the OS Bluetooth stack will do what it thinks is best.

macOS

BLE Client for CoreBluetooth on macOS

Created on 2019-06-26 by kevincar <kevincarrolldavis@gmail.com>

class bleak.backends.corebluetooth.client.BleakClientCoreBluetooth(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)[source]

CoreBluetooth class interface for BleakClient

Parameters: address_or_ble_device (BLEDevice or str) – The Bluetooth address of the BLE peripheral to connect to or the BLEDevice object representing it.
Keyword Arguments: timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.

async connect(**kwargs) → bool[source]

Connect to a specified Peripheral

Keyword Arguments: timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.
Returns: Boolean representing connection status.

async disconnect() → bool[source]: Disconnect from the peripheral device

async get_rssi() → int[source]: To get RSSI value in dBm of the connected Peripheral

async get_services(**kwargs) → bleak.backends.service.BleakGATTServiceCollection[source]

Get all services registered for this GATT server.

Returns: A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

property is_connected: bool: Checks for current active connection

property mtu_size: int: Get ATT MTU size for active connection

async pair(*args, **kwargs) → bool[source]

Attempt to pair with a peripheral.

Note

This is not available on macOS since there is not explicit method to do a pairing, Instead the docs state that it “auto-pairs” when trying to read a characteristic that requires encryption, something Bleak cannot do apparently.

Reference:

Apple Docs

Stack Overflow post #1

Stack Overflow post #2

Returns: Boolean regarding success of pairing.

async read_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], use_cached=False, **kwargs) → bytearray[source]

Perform read operation on the specified GATT characteristic.

Parameters

char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
use_cached (bool) – False forces macOS to read the value from the device again and not use its own cached value. Defaults to False.

Returns

(bytearray) The read data.

async read_gatt_descriptor(handle: int, use_cached=False, **kwargs) → bytearray[source]

Perform read operation on the specified GATT descriptor.

Parameters

handle (int) – The handle of the descriptor to read from.
use_cached (bool) – False forces Windows to read the value from the device again and not use its own cached value. Defaults to False.

Returns

(bytearray) The read data.

async start_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None[source]

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be a integer handle of the characteristic generating the data and the second will be a bytearray containing the data sent from the connected server.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)

Parameters

char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
callback (function) – The function to be called on notification.

async stop_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID]) → None[source]

Deactivate notification/indication on a specified characteristic.

Parameters: char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

async unpair() → bool[source]: Returns:

async write_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], data: Union[bytes, bytearray, memoryview], response: bool = False) → None[source]

Perform a write operation of the specified GATT characteristic.

Parameters

char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
data (bytes or bytearray) – The data to send.
response (bool) – If write-with-response operation should be done. Defaults to False.

async write_gatt_descriptor(handle: int, data: Union[bytes, bytearray, memoryview]) → None[source]

Perform a write operation on the specified GATT descriptor.

Parameters

handle (int) – The handle of the descriptor to read from.
data (bytes or bytearray) – The data to send.

Linux Distributions with BlueZ

BLE Client for BlueZ on Linux

class bleak.backends.bluezdbus.client.BleakClientBlueZDBus(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)[source]

A native Linux Bleak Client

Implemented by using the BlueZ DBUS API.

Parameters

address_or_ble_device (BLEDevice or str) – The Bluetooth address of the BLE peripheral to connect to or the BLEDevice object representing it.

Keyword Arguments

timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.
disconnected_callback (callable) – Callback that will be scheduled in the event loop when the client is disconnected. The callable must take one argument, which will be this client object.
adapter (str) – Bluetooth adapter to use for discovery.

async connect(**kwargs) → bool[source]

Connect to the specified GATT server.

Keyword Arguments

timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.

Returns

Boolean representing connection status.

Raises

BleakError – If the device is already connected or if the device could not be found.
BleakDBusError – If there was a D-Bus error
asyncio.TimeoutError – If the connection timed out

async disconnect() → bool[source]

Disconnect from the specified GATT server.

Returns

Boolean representing if device is disconnected.

Raises

BleakDBusError – If there was a D-Bus error
asyncio.TimeoutError if the device was not disconnected within 10 seconds –

async get_services(**kwargs) → bleak.backends.service.BleakGATTServiceCollection[source]

Get all services registered for this GATT server.

Returns: A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

property is_connected: bool

Check connection status between this client and the server.

Returns: Boolean representing connection status.

property mtu_size: int: Get ATT MTU size for active connection

async pair(*args, **kwargs) → bool[source]

Pair with the peripheral.

You can use ConnectDevice method if you already know the MAC address of the device. Else you need to StartDiscovery, Trust, Pair and Connect in sequence.

Returns: Boolean regarding success of pairing.

async read_gatt_char(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID], **kwargs) → bytearray[source]

Perform read operation on the specified GATT characteristic.

Parameters: char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.
Returns: (bytearray) The read data.

async read_gatt_descriptor(handle: int, **kwargs) → bytearray[source]

Perform read operation on the specified GATT descriptor.

Parameters: handle (int) – The handle of the descriptor to read from.
Returns: (bytearray) The read data.

async start_notify(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None[source]

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be a integer handle of the characteristic generating the data and the second will be a bytearray containing the data sent from the connected server.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)

Parameters

char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.
callback (function) – The function to be called on notification.

async stop_notify(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID]) → None[source]

Deactivate notification/indication on a specified characteristic.

Parameters: char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.

async unpair() → bool[source]

Unpair with the peripheral.

Returns: Boolean regarding success of unpairing.

async write_gatt_char(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID], data: Union[bytes, bytearray, memoryview], response: bool = False) → None[source]

Perform a write operation on the specified GATT characteristic.

Note

The version check below is for the “type” option to the “Characteristic.WriteValue” method that was added to Bluez in 5.51 Before that commit, Characteristic.WriteValue was only “Write with response”. Characteristic.AcquireWrite was added in Bluez 5.46 which can be used to “Write without response”, but for older versions of Bluez, it is not possible to “Write without response”.

Parameters

char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.
data (bytes or bytearray) – The data to send.
response (bool) – If write-with-response operation should be done. Defaults to False.

async write_gatt_descriptor(handle: int, data: Union[bytes, bytearray, memoryview]) → None[source]

Perform a write operation on the specified GATT descriptor.

Parameters

handle (int) – The handle of the descriptor to read from.
data (bytes or bytearray) – The data to send.

Python-for-Android/Kivy

BLE Client for python-for-android

class bleak.backends.p4android.client.BleakClientP4Android(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)[source]

A python-for-android Bleak Client

Parameters

address_or_ble_device (BLEDevice or str) – The Bluetooth address of the BLE peripheral to connect to or the BLEDevice object representing it.

Keyword Arguments

disconnected_callback (callable) – Callback that will be scheduled in the event loop when the client is disconnected. The callable must take one argument, which will be this client object.
adapter (str) – Bluetooth adapter to use for discovery. [unused]

async connect(**kwargs) → bool[source]

Connect to the specified GATT server.

Returns: Boolean representing connection status.

async disconnect() → bool[source]

Disconnect from the specified GATT server.

Returns: Boolean representing if device is disconnected.

async get_services() → bleak.backends.service.BleakGATTServiceCollection[source]

Get all services registered for this GATT server.

Returns: A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

property is_connected: bool

Check connection status between this client and the server.

Returns: Boolean representing connection status.

async pair(*args, **kwargs) → bool[source]

Pair with the peripheral.

You can use ConnectDevice method if you already know the MAC address of the device. Else you need to StartDiscovery, Trust, Pair and Connect in sequence.

Returns: Boolean regarding success of pairing.

async read_gatt_char(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID], **kwargs) → bytearray[source]

Perform read operation on the specified GATT characteristic.

Parameters: char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it.
Returns: (bytearray) The read data.

async read_gatt_descriptor(desc_specifier: Union[bleak.backends.p4android.descriptor.BleakGATTDescriptorP4Android, str, uuid.UUID], **kwargs) → bytearray[source]

Perform read operation on the specified GATT descriptor.

Parameters: desc_specifier (BleakGATTDescriptorP4Android, str or UUID) – The descriptor to read from, specified by either UUID or directly by the BleakGATTDescriptorP4Android object representing it.
Returns: (bytearray) The read data.

async start_notify(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None[source]

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be an integer handle of the characteristic generating the data and the second will be a bytearray containing the data sent from the connected server.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)

Parameters

char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it.
callback (function) – The function to be called on notification.

async stop_notify(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID]) → None[source]

Deactivate notification/indication on a specified characteristic.

Parameters: char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it.

async unpair() → bool[source]

Unpair with the peripheral.

Returns: Boolean regarding success of unpairing.

async write_gatt_char(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID], data: bytearray, response: bool = False) → None[source]

Perform a write operation on the specified GATT characteristic.

Parameters

char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it.
data (bytes or bytearray) – The data to send.
response (bool) – If write-with-response operation should be done. Defaults to False.

async write_gatt_descriptor(desc_specifier: Union[bleak.backends.p4android.descriptor.BleakGATTDescriptorP4Android, str, uuid.UUID], data: bytearray) → None[source]

Perform a write operation on the specified GATT descriptor.

Parameters

desc_specifier (BleakGATTDescriptorP4Android, str or UUID) – The descriptor to write to, specified by either UUID or directly by the BleakGATTDescriptorP4Android object representing it.
data (bytes or bytearray) – The data to send.

Scanning Clients

Interface

class bleak.backends.scanner.AdvertisementData(**kwargs)[source]: Wrapper around the advertisement data that each platform returns upon discovery

class bleak.backends.scanner.BaseBleakScanner(detection_callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]], service_uuids: Optional[List[str]])[source]

Interface for Bleak Bluetooth LE Scanners

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.

async classmethod discover(timeout=5.0, **kwargs) → List[bleak.backends.device.BLEDevice][source]

Scan continuously for timeout seconds and return discovered devices.

Parameters: timeout – Time to scan for.
Keyword Arguments: **kwargs – Implementations might offer additional keyword arguments sent to the constructor of the BleakScanner class.

Returns:

abstract property discovered_devices: List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

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

async classmethod find_device_by_address(device_identifier: str, timeout: float = 10.0, **kwargs) → Optional[bleak.backends.device.BLEDevice][source]

A convenience method for obtaining a BLEDevice object specified by Bluetooth address or (macOS) UUID address.

Parameters

device_identifier (str) – The Bluetooth/UUID address of the Bluetooth peripheral sought.
timeout (float) – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

Keyword Arguments

adapter (str) – Bluetooth adapter to use for discovery.

Returns

The BLEDevice sought or None if not detected.

async classmethod find_device_by_filter(filterfunc: Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], bool], timeout: float = 10.0, **kwargs) → Optional[bleak.backends.device.BLEDevice][source]

A convenience method for obtaining a BLEDevice object specified by a filter function.

Parameters

filterfunc (AdvertisementDataFilter) – A function that is called for every BLEDevice found. It should return True only for the wanted device.
timeout (float) – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

Keyword Arguments

adapter (str) – Bluetooth adapter to use for discovery.

Returns

The BLEDevice sought or None if not detected.

async get_discovered_devices() → List[bleak.backends.device.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.

register_detection_callback(callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]]) → None[source]

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

If another callback has already been registered, it will be replaced with callback. None can be used to remove the current callback.

The callback is a function or coroutine that takes two arguments: BLEDevice and AdvertisementData.

Parameters: callback – A function, coroutine or None.

abstract set_scanning_filter(**kwargs)[source]

Set scanning filter for the BleakScanner.

Parameters: **kwargs – The filter details. This will differ a lot between backend implementations.

abstract async start()[source]: Start scanning for devices

abstract async stop()[source]: Stop scanning for devices

Windows

class bleak.backends.winrt.scanner.BleakScannerWinRT(detection_callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]] = None, service_uuids: Optional[List[str]] = None, scanning_mode: Literal['active', 'passive'] = 'active', **kwargs)[source]

The native Windows Bleak BLE Scanner.

Implemented using Python/WinRT.

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.
scanning_mode – Set to "passive" to avoid the "active" scanning mode.

property discovered_devices: List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

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

set_scanning_filter(**kwargs)[source]

Set a scanning filter for the BleakScanner.

Keyword Arguments

SignalStrengthFilter (Windows.Devices.Bluetooth.BluetoothSignalStrengthFilter) – A BluetoothSignalStrengthFilter object used for configuration of Bluetooth LE advertisement filtering that uses signal strength-based filtering.
AdvertisementFilter (Windows.Devices.Bluetooth.Advertisement.BluetoothLEAdvertisementFilter) – A BluetoothLEAdvertisementFilter object used for configuration of Bluetooth LE advertisement filtering that uses payload section-based filtering.

async start()[source]: Start scanning for devices

async stop()[source]: Stop scanning for devices

macOS

class bleak.backends.corebluetooth.scanner.BleakScannerCoreBluetooth(detection_callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]] = None, service_uuids: Optional[List[str]] = None, scanning_mode: Literal['active', 'passive'] = 'active', **kwargs)[source]

The native macOS Bleak BLE Scanner.

Documentation: https://developer.apple.com/documentation/corebluetooth/cbcentralmanager

CoreBluetooth doesn’t explicitly use Bluetooth addresses to identify peripheral devices because private devices may obscure their Bluetooth addresses. To cope with this, CoreBluetooth utilizes UUIDs for each peripheral. Bleak uses this for the BLEDevice address on macOS.

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. Not supported on macOS! Will raise BleakError if set to "passive"
**timeout (float) – The scanning timeout to be used, in case of missing stopScan_ method.

property discovered_devices: List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

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

set_scanning_filter(**kwargs)[source]

Set scanning filter for the scanner.

Note

This is not implemented for macOS yet.

Raises: NotImplementedError –

async start()[source]: Start scanning for devices

async stop()[source]: Stop scanning for devices

Linux Distributions with BlueZ

class bleak.backends.bluezdbus.scanner.BleakScannerBlueZDBus(detection_callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]] = None, service_uuids: Optional[List[str]] = None, scanning_mode: Literal['active', 'passive'] = 'active', *, bluez: bleak.backends.bluezdbus.scanner.BlueZScannerArgs = {}, **kwargs)[source]

The native Linux Bleak BLE Scanner.

For possible values for filters, see the parameters to the SetDiscoveryFilter method in the BlueZ docs

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. Specifying this also enables scanning while the screen is off on Android.
scanning_mode – Set to "passive" to avoid the "active" scanning mode.
**bluez – Dictionary of arguments specific to the BlueZ backend.
**adapter (str) – Bluetooth adapter to use for discovery.

property discovered_devices: List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

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

set_scanning_filter(**kwargs)[source]

Sets OS level scanning filters for the BleakScanner.

For possible values for filters, see the parameters to the SetDiscoveryFilter method in the BlueZ docs

See variant types here: <https://python-dbus-next.readthedocs.io/en/latest/type-system/>

Keyword Arguments: filters (dict) – A dict of filters to be applied on discovery.

async start()[source]: Start scanning for devices

async stop()[source]: Stop scanning for devices

class bleak.backends.bluezdbus.scanner.BlueZDiscoveryFilters[source]

class bleak.backends.bluezdbus.scanner.BlueZScannerArgs[source]

BleakScanner args that are specific to the BlueZ backend.

filters: bleak.backends.bluezdbus.scanner.BlueZDiscoveryFilters

Filters to pass to the adapter SetDiscoveryFilter D-Bus method.

Only used for active scanning.

or_patterns: List[Union[bleak.backends.bluezdbus.advertisement_monitor.OrPattern, Tuple[int, bleak.assigned_numbers.AdvertisementDataType, bytes]]]

Or patterns to pass to the AdvertisementMonitor1 D-Bus interface.

Only used for passive scanning.

Python-for-Android/Kivy

class bleak.backends.p4android.scanner.BleakScannerP4Android(detection_callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]] = None, service_uuids: Optional[List[str]] = None, scanning_mode: Literal['active', 'passive'] = 'active', **kwargs)[source]

The python-for-android Bleak BLE Scanner.

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. Specifying this also enables scanning while the screen is off on Android.
scanning_mode – Set to "passive" to avoid the "active" scanning mode.

property discovered_devices: List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

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

set_scanning_filter(**kwargs)[source]

Set scanning filter for the BleakScanner.

Parameters: **kwargs – The filter details. This will differ a lot between backend implementations.

async start()[source]: Start scanning for devices

async stop()[source]: Stop scanning for devices

Class representing BLE devices

Generated by bleak.discover() and bleak.backends.scanning.BaseBleakScanner.

Wrapper class for Bluetooth LE servers returned from calling bleak.discover().

Created on 2018-04-23 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.device.BLEDevice(address, name, details=None, rssi=0, **kwargs)[source]

A simple wrapper class representing a BLE server detected during a discover call.

When using Windows backend, details attribute is a Windows.Devices.Bluetooth.Advertisement.BluetoothLEAdvertisement object, unless it is created with the Windows.Devices.Enumeration discovery method, then is is a Windows.Devices.Enumeration.DeviceInformation.
When using Linux backend, details attribute is a dict with keys path which has the string path to the DBus device object and props which houses the properties dictionary of the D-Bus Device.
When using macOS backend, details attribute will be a CBPeripheral object.

address: The Bluetooth address of the device on this machine.

details: The OS native details required for connecting to the device.

metadata: Device specific details. Contains a uuids key which is a list of service UUIDs and a manufacturer_data field with a bytes-object from the advertised data.

name: The advertised name of the device.

rssi: RSSI, if available

GATT objects

Gatt Service Collection class and interface class for the Bleak representation of a GATT Service.

Created on 2019-03-19 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.service.BleakGATTService(obj)[source]

Interface for the Bleak representation of a GATT Service.

abstract add_characteristic(characteristic: bleak.backends.characteristic.BleakGATTCharacteristic)[source]

Add a BleakGATTCharacteristic to the service.

Should not be used by end user, but rather by bleak itself.

abstract property characteristics: List[bleak.backends.characteristic.BleakGATTCharacteristic]: List of characteristics for this service

property description: str: String description for this service

get_characteristic(uuid: Union[str, uuid.UUID]) → Optional[bleak.backends.characteristic.BleakGATTCharacteristic][source]

Get a characteristic by UUID.

Parameters: uuid – The UUID to match.
Returns: The first characteristic matching uuid or None if no matching characteristic was found.

abstract property handle: int: The handle of this service

abstract property uuid: str: The UUID to this service

class bleak.backends.service.BleakGATTServiceCollection[source]

Simple data container for storing the peripheral’s service complement.

add_characteristic(characteristic: bleak.backends.characteristic.BleakGATTCharacteristic)[source]

Add a BleakGATTCharacteristic to the service collection.

Should not be used by end user, but rather by bleak itself.

add_descriptor(descriptor: bleak.backends.descriptor.BleakGATTDescriptor)[source]

Add a BleakGATTDescriptor to the service collection.

Should not be used by end user, but rather by bleak itself.

add_service(service: bleak.backends.service.BleakGATTService)[source]

Add a BleakGATTService to the service collection.

Should not be used by end user, but rather by bleak itself.

property characteristics: Dict[int, bleak.backends.characteristic.BleakGATTCharacteristic]: Returns dictionary of handles mapping to BleakGATTCharacteristic

property descriptors: Dict[int, bleak.backends.descriptor.BleakGATTDescriptor]: Returns a dictionary of integer handles mapping to BleakGATTDescriptor

get_characteristic(specifier: Union[int, str, uuid.UUID]) → Optional[bleak.backends.characteristic.BleakGATTCharacteristic][source]: Get a characteristic by handle (int) or UUID (str or uuid.UUID)

get_descriptor(handle: int) → Optional[bleak.backends.descriptor.BleakGATTDescriptor][source]: Get a descriptor by integer handle

get_service(specifier: Union[int, str, uuid.UUID]) → Optional[bleak.backends.service.BleakGATTService][source]: Get a service by handle (int) or UUID (str or uuid.UUID)

property services: Dict[int, bleak.backends.service.BleakGATTService]: Returns dictionary of handles mapping to BleakGATTService

Interface class for the Bleak representation of a GATT Characteristic

Created on 2019-03-19 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.characteristic.BleakGATTCharacteristic(obj: Any)[source]

Interface for the Bleak representation of a GATT Characteristic

abstract add_descriptor(descriptor: bleak.backends.descriptor.BleakGATTDescriptor)[source]

Add a BleakGATTDescriptor to the characteristic.

Should not be used by end user, but rather by bleak itself.

property description: str: Description for this characteristic

abstract property descriptors: List: List of descriptors for this service

abstract get_descriptor(specifier: Union[int, str, uuid.UUID]) → Optional[bleak.backends.descriptor.BleakGATTDescriptor][source]: Get a descriptor by handle (int) or UUID (str or uuid.UUID)

abstract property handle: int: The handle for this characteristic

abstract property properties: List[str]: Properties of this characteristic

abstract property service_handle: int: The integer handle of the Service containing this characteristic

abstract property service_uuid: str: The UUID of the Service containing this characteristic

abstract property uuid: str: The UUID for this characteristic

class bleak.backends.characteristic.GattCharacteristicsFlags(value)[source]: An enumeration.

Interface class for the Bleak representation of a GATT Descriptor

Created on 2019-03-19 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.descriptor.BleakGATTDescriptor(obj: Any)[source]

Interface for the Bleak representation of a GATT Descriptor

abstract property characteristic_handle: int: handle for the characteristic that this descriptor belongs to

abstract property characteristic_uuid: str: UUID for the characteristic that this descriptor belongs to

property description: str: A text description of what this descriptor represents

abstract property handle: int: Integer handle for this descriptor

abstract property uuid: str: UUID for this descriptor

Exceptions

exception bleak.exc.BleakDBusError(dbus_error: str, error_body: list)[source]

Specialized exception type for D-Bus errors.

property dbus_error: str: Gets the D-Bus error name, e.g. org.freedesktop.DBus.Error.UnknownObject.

property dbus_error_details: Optional[str]: Gets the optional D-Bus error details, e.g. ‘Invalid UUID’.

exception bleak.exc.BleakError[source]: Base Exception for bleak.

Utilities

bleak.uuids.register_uuids(uuids_to_descriptions: Dict[str, str]) → None[source]

Add or modify the mapping of 128-bit UUIDs for services and characteristics to descriptions.

Parameters: uuids_to_descriptions – A dictionary of new mappings