API reference

Contents:

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: str, name: Optional[str], details: Any, rssi: int, **kwargs)[source]

A simple wrapper class representing a BLE server detected during scanning.

address: The Bluetooth address of the device on this machine (UUID on macOS).

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

property metadata: dict: Gets additional advertisement data for the device.

Deprecated since version 0.19.0: Use AdvertisementData from detection callback or BleakScanner.discovered_devices_and_advertisement_data instead.

name: The operating system name of the device (not necessarily the local name from the advertising data), suitable for display to the user.

property rssi: int: Gets the RSSI of the last received advertisement.

Deprecated since version 0.19.0: Use AdvertisementData from detection callback or BleakScanner.discovered_devices_and_advertisement_data instead.

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: BleakGATTCharacteristic)[source]

Add a BleakGATTCharacteristic to the service.

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

abstract property characteristics: List[BleakGATTCharacteristic]: List of characteristics for this service

property description: str: String description for this service

get_characteristic(uuid: Union[str, UUID]) → Optional[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: BleakGATTCharacteristic)[source]

Add a BleakGATTCharacteristic to the service collection.

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

add_descriptor(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: 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, BleakGATTCharacteristic]: Returns dictionary of handles mapping to BleakGATTCharacteristic

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

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

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

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

property services: Dict[int, 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, max_write_without_response_size: int)[source]

Interface for the Bleak representation of a GATT Characteristic

abstract add_descriptor(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[BleakGATTDescriptor]: List of descriptors for this service

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

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

property max_write_without_response_size: int: Gets the maximum size in bytes that can be used for the data argument of BleakClient.write_gatt_char() when response=False.

Warning

Linux quirk: For BlueZ versions < 5.62, this property will always return 20.

New in version 0.16.0.

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

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

Utilities

bleak.uuids.normalize_uuid_16(uuid: int) → str[source]

Normaizes a 16-bit integer UUID to the format used by Bleak.

Returns: 128-bit UUID as string with the format "0000xxxx-1000-8000-00805f9b34fb".

Example:

uuid = normalize_uuid_16(0x1234)
# uuid == "00001234-1000-8000-00805f9b34fb"

New in version 0.21.

bleak.uuids.normalize_uuid_32(uuid: int) → str[source]

Normaizes a 32-bit integer UUID to the format used by Bleak.

Returns: 128-bit UUID as string with the format "xxxxxxxx-1000-8000-00805f9b34fb".

Example:

uuid = normalize_uuid_32(0x12345678)
# uuid == "12345678-1000-8000-00805f9b34fb"

New in version 0.21.

bleak.uuids.normalize_uuid_str(uuid: str) → str[source]

Normaizes a UUID to the format used by Bleak.

Converted to lower case.
16-bit and 32-bit UUIDs are expanded to 128-bit.

Example:

# 16-bit
uuid1 = normalize_uuid_str("1234")
# uuid1 == "00001234-1000-8000-00805f9b34fb"

# 32-bit
uuid2 = normalize_uuid_str("12345678")
# uuid2 == "12345678-1000-8000-00805f9b34fb"

# 128-bit
uuid3 = normalize_uuid_str("12345678-1234-1234-1234567890ABC")
# uuid3 == "12345678-1234-1234-1234567890abc"

New in version 0.20.

Changed in version 0.21: Added support for 32-bit UUIDs.

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

Deprecated

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.