bleak package

Subpackages

Submodules

bleak.assigned_numbers module

Bluetooth Assigned Numbers

This module contains useful assigned numbers from the Bluetooth spec.

See <https://www.bluetooth.com/specifications/assigned-numbers/>.

class bleak.assigned_numbers.AdvertisementDataType(value)[source]

Bases: enum.IntEnum

Generic Access Profile advertisement data types.

Source <https://btprodspecificationrefs.blob.core.windows.net/assigned-numbers/Assigned%20Number%20Types/Generic%20Access%20Profile.pdf>.

New in version 0.15.0.

CLASS_OF_DEVICE = 13
COMPLETE_LIST_SERVICE_UUID128 = 7
COMPLETE_LIST_SERVICE_UUID16 = 3
COMPLETE_LIST_SERVICE_UUID32 = 5
COMPLETE_LOCAL_NAME = 9
FLAGS = 1
INCOMPLETE_LIST_SERVICE_UUID128 = 6
INCOMPLETE_LIST_SERVICE_UUID16 = 2
INCOMPLETE_LIST_SERVICE_UUID32 = 4
MANUFACTURER_SPECIFIC_DATA = 255
SERVICE_DATA_UUID128 = 33
SERVICE_DATA_UUID16 = 22
SERVICE_DATA_UUID32 = 32
SHORTENED_LOCAL_NAME = 8
TX_POWER_LEVEL = 10

bleak.exc module

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

Bases: bleak.exc.BleakError

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.BleakDeviceNotFoundError(identifier: str, *args: object)[source]

Bases: bleak.exc.BleakError

Exception which is raised if a device can not be found by connect, pair and unpair. This is the case if the OS Bluetooth stack has never seen this device or it was removed and forgotten.

identifier: str
exception bleak.exc.BleakError[source]

Bases: Exception

Base Exception for bleak.

bleak.uuids module

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

bleak.uuids.uuidstr_to_str(uuid_)[source]

Module contents

Top-level package for bleak.

class bleak.BleakClient(address_or_ble_device: Union[BLEDevice, str], disconnected_callback: Optional[Callable[[BleakClient], None]] = None, *, timeout: float = 10.0, winrt: WinRTClientArgs = {}, backend: Optional[Type[BaseBleakClient]] = None, **kwargs)[source]

Bases: object

The Client interface for connecting to a specific BLE GATT server and communicating with it.

A BleakClient can be used as an asynchronous context manager in which case it automatically connects and disconnects.

How many BLE connections can be active simultaneously, and whether connections can be active while scanning depends on the Bluetooth adapter hardware.

Parameters

  • address_or_ble_device – A BLEDevice received from a BleakScanner or a Bluetooth address (device UUID on macOS).

  • disconnected_callback – 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.

  • timeout – Timeout in seconds passed to the implicit discover call when address_or_ble_device is not a BLEDevice. Defaults to 10.0.

  • winrt – Dictionary of WinRT/Windows platform-specific options.

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

  • **kwargs – Additional keyword arguments for backwards compatibility.

Warning

Although example code frequently initializes BleakClient with a Bluetooth address for simplicity, it is not recommended to do so for more complex use cases. There are several known issues with providing a Bluetooth address as the address_or_ble_device argument.

  1. macOS does not provide access to the Bluetooth address for privacy/ security reasons. Instead it creates a UUID for each Bluetooth device which is used in place of the address on this platform.

  2. Providing an address or UUID instead of a BLEDevice causes the connect() method to implicitly call BleakScanner.discover(). This is known to cause problems when trying to connect to multiple devices at the same time.

Changed in version 0.15.0: disconnected_callback is no longer keyword-only. Added winrt parameter.

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

property address: str

Gets the Bluetooth address of this device (UUID on macOS).

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

Connect to the specified GATT server.

Parameters

**kwargs – For backwards compatibility - should not be used.

Returns

Always returns True for backwards compatibility.

async disconnect() → bool[source]

Disconnect from the specified GATT server.

Returns

Always returns True for backwards compatibility.

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

Get all services registered for this GATT server.

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

Returns

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

property is_connected: bool

Check connection status between this client and the GATT server.

Returns

Boolean representing connection status.

property mtu_size: int

Gets the negotiated MTU size in bytes for the active connection.

Consider using bleak.backends.characteristic.BleakGATTCharacteristic.max_write_without_response_size instead.

Warning

The BlueZ backend will always return 23 (the minimum MTU size). See the mtu_size.py example for a way to hack around this.

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

Pair with the specified GATT server.

This method is not available on macOS. Instead of manually initiating paring, the user will be prompted to pair the device the first time that a characteristic that requires authentication is read or written. This method may have backend-specific additional keyword arguments.

Returns

Always returns True for backwards compatibility.

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 – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

Returns

The read data.

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

Perform read operation on the specified GATT descriptor.

Parameters

handle – The handle of the descriptor to read from.

Returns

The read data.

property services: bleak.backends.service.BleakGATTServiceCollection

Gets the collection of GATT services available on the device.

The returned value is only valid as long as the device is connected.

set_disconnected_callback(callback: Optional[Callable[[bleak.BleakClient], None]], **kwargs) → None[source]

Set the disconnect callback.

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

Parameters

callback – callback to be called on disconnection.

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

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be the characteristic and the second will be a bytearray containing the data received.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")

client.start_notify(char_uuid, callback)
Parameters

  • char_specifier – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

  • callback – The function to be called on notification. Can be regular function or async function.

Changed in version 0.18.0: The first argument of the callback is now a BleakGATTCharacteristic instead of an int.

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 – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

Tip

Notifications are stopped automatically on disconnect, so this method does not need to be called unless notifications need to be stopped some time before the device disconnects.

async unpair() → bool[source]

Unpair from the specified GATT server.

Unpairing will also disconnect the device.

This method is only available on Windows and Linux and will raise an exception on other platforms.

Returns

Always returns True for backwards compatibility.

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 – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.

  • data – The data to send.

  • response – 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 – The handle of the descriptor to read from.

  • data – The data to send.

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

Bases: object

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.

  • 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.

async classmethod discover(timeout: float = 5.0, *, return_adv: Literal[False] = 'False', **kwargs) → List[bleak.backends.device.BLEDevice][source]
async classmethod discover(timeout: float = 5.0, *, return_adv: Literal[True], **kwargs) → Dict[str, Tuple[bleak.backends.device.BLEDevice, bleak.backends.scanner.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.

property discovered_devices: List[bleak.backends.device.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 discovered_devices_and_advertisement_data: Dict[str, Tuple[bleak.backends.device.BLEDevice, bleak.backends.scanner.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.

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

Obtain a BLEDevice for a BLE server 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]

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.

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.

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.

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 start()[source]

Start scanning for devices

async stop()[source]

Stop scanning for devices

bleak.cli()[source]
bleak.discover(*args, **kwargs)[source]

Deprecated since version 0.17.0: This method will be removed in a future version of Bleak. Use BleakScanner.discover() instead.