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
orNone
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()
whenresponse=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
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.BleakCharacteristicNotFoundError(char_specifier: 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[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’.
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.