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

Interface for the Bleak representation of a GATT Service.

abstract add_characteristic(characteristic: BleakGATTCharacteristic) None[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) None[source]

Add a BleakGATTCharacteristic to the service collection.

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

add_descriptor(descriptor: BleakGATTDescriptor) None[source]

Add a BleakGATTDescriptor to the service collection.

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

add_service(service: BleakGATTService) None[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) None[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.BleakCharacteristicNotFoundError(char_specifier: Union[int, str, UUID])[source]

Exception which is raised if a device does not support a characteristic.

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.