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().

class bleak.backends.device.BLEDevice(address: str, name: str | None, details: Any, **kwargs: Any)[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.

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

GATT objects

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

class bleak.backends.service.BleakGATTService(obj: Any, handle: int, uuid: str)[source]

The Bleak representation of a GATT Service.

add_characteristic(characteristic: BleakGATTCharacteristic) → None[source]

Add a BleakGATTCharacteristic to the service.

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

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

property description: str: String description for this service

get_characteristic(uuid: str | UUID) → BleakGATTCharacteristic | None[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.

property handle: int: The handle of this service

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: int | str | UUID) → BleakGATTCharacteristic | None[source]: Get a characteristic by handle (int) or UUID (str or uuid.UUID)

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

get_service(specifier: int | str | UUID) → BleakGATTService | None[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

class bleak.backends.characteristic.BleakGATTCharacteristic(obj: Any, handle: int, uuid: str, properties: list[CharacteristicPropertyName], max_write_without_response_size: Callable[[], int], service: BleakGATTService)[source]

The Bleak representation of a GATT Characteristic

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

property descriptors: list[BleakGATTDescriptor]: List of descriptors for this service

get_descriptor(specifier: int | str | UUID) → BleakGATTDescriptor | None[source]: Get a descriptor by handle (int) or UUID (str or uuid.UUID)

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.

In rare cases, a device may take a long time to update this value, so reading this property may return the default value of 20 and reading it again after a some time may return the expected higher value.

If you really need to wait for a higher value, you can do something like this:

async with asyncio.timeout(10):
    while char.max_write_without_response_size == 20:
        await asyncio.sleep(0.5)

Warning

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

Added in version 0.16.

property properties: list[Literal['broadcast', 'read', 'write-without-response', 'write', 'notify', 'indicate', 'authenticated-signed-writes', 'extended-properties', 'reliable-write', 'writable-auxiliaries', 'encrypt-read', 'encrypt-write', 'encrypt-authenticated-read', 'encrypt-authenticated-write', 'authorize']]: Properties of this characteristic

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

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

property uuid: str: The UUID for this characteristic

class bleak.backends.characteristic.GattCharacteristicsFlags(*values)[source]

Interface class for the Bleak representation of a GATT Descriptor

class bleak.backends.descriptor.BleakGATTDescriptor(obj: Any, handle: int, uuid: str, characteristic: BleakGATTCharacteristic)[source]

The Bleak representation of a GATT Descriptor

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

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

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

property handle: int: Integer handle for this descriptor

property uuid: str: UUID for this descriptor

Exceptions

exception bleak.exc.BleakBluetoothNotAvailableError(msg: str, reason: BleakBluetoothNotAvailableReason)[source]

Exception which is raised if the Bluetooth access is not available for some reason.

Added in version 2.0.

property reason: BleakBluetoothNotAvailableReason: Gets the reason why Bluetooth is not available.

class bleak.exc.BleakBluetoothNotAvailableReason(*values)[source]

Reasons for Bluetooth not being available.

Added in version 2.0.

DENIED_BY_SYSTEM = 5: Using Bluetooth was denied by the system. E.g. because of a system administrator policy.

DENIED_BY_UNKNOWN = 6: Permission to use Bluetooth was denied for an unknown reason.

DENIED_BY_USER = 4: The user denied permission for the app to use Bluetooth when prompted.

NO_BLE_CENTRAL_ROLE = 2: The Bluetooth radio does not support the Central role. (E.g. classic-only adapters.)

NO_BLUETOOTH = 1: The system does not support Bluetooth. I.e. there is no Bluetooth radio.

POWERED_OFF = 3: Bluetooth is not currently available because the radio is turned off.

UNKNOWN = 7: Bluetooth is not available for an unknown reason.

exception bleak.exc.BleakCharacteristicNotFoundError(char_specifier: int | str | UUID)[source]: Exception which is raised if a device does not support a characteristic.

Added in version 0.22.

exception bleak.exc.BleakDBusError(dbus_error: str, error_body: list[Any])[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: str | None: 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.

Added in version 0.19.

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-0000-1000-8000-00805f9b34fb".

Example:

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

Added 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-0000-1000-8000-00805f9b34fb".

Example:

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

Added 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-0000-1000-8000-00805f9b34fb"

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

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

Added 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