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, name=None, details=None, rssi=0, **kwargs)[source]

A simple wrapper class representing a BLE server detected during a discover call.

  • When using Windows backend, details attribute is a Windows.Devices.Bluetooth.Advertisement.BluetoothLEAdvertisement object, unless it is created with the Windows.Devices.Enumeration discovery method, then is is a Windows.Devices.Enumeration.DeviceInformation.

  • When using Linux backend, details attribute is a dict with keys path which has the string path to the DBus device object and props which houses the properties dictionary of the D-Bus Device.

  • When using macOS backend, details attribute will be a CBPeripheral object.

address

The Bluetooth address of the device on this machine.

details

The OS native details required for connecting to the device.

metadata

Device specific details. Contains a uuids key which is a list of service UUIDs and a manufacturer_data field with a bytes-object from the advertised data.

name

The advertised name of the device.

rssi

RSSI, if available

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: bleak.backends.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[bleak.backends.characteristic.BleakGATTCharacteristic]

List of characteristics for this service

property description: str

String description for this service

get_characteristic(uuid: Union[str, uuid.UUID]) Optional[bleak.backends.characteristic.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: bleak.backends.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: bleak.backends.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: bleak.backends.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, bleak.backends.characteristic.BleakGATTCharacteristic]

Returns dictionary of handles mapping to BleakGATTCharacteristic

property descriptors: Dict[int, bleak.backends.descriptor.BleakGATTDescriptor]

Returns a dictionary of integer handles mapping to BleakGATTDescriptor

get_characteristic(specifier: Union[int, str, uuid.UUID]) Optional[bleak.backends.characteristic.BleakGATTCharacteristic][source]

Get a characteristic by handle (int) or UUID (str or uuid.UUID)

get_descriptor(handle: int) Optional[bleak.backends.descriptor.BleakGATTDescriptor][source]

Get a descriptor by integer handle

get_service(specifier: Union[int, str, uuid.UUID]) Optional[bleak.backends.service.BleakGATTService][source]

Get a service by handle (int) or UUID (str or uuid.UUID)

property services: Dict[int, bleak.backends.service.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: bleak.backends.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[bleak.backends.descriptor.BleakGATTDescriptor]

List of descriptors for this service

abstract get_descriptor(specifier: Union[int, str, uuid.UUID]) Optional[bleak.backends.descriptor.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.

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