bleak.backends.bluezdbus package

Submodules

bleak.backends.bluezdbus.characteristic module

class bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus(obj: dict, object_path: str, service_uuid: str, service_handle: int)[source]

Bases: bleak.backends.characteristic.BleakGATTCharacteristic

GATT Characteristic implementation for the BlueZ DBus backend

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 descriptors: List

List of descriptors for this service

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)

property handle: int

The handle of this characteristic

property path: str

The DBus path. Mostly needed by bleak, not by end user

property properties: List

Properties of this characteristic

Returns the characteristics Flags present in the DBus API.

property service_handle: int

The handle of the Service containing this characteristic

property service_uuid: str

The uuid of the Service containing this characteristic

property uuid: str

The uuid of this characteristic

bleak.backends.bluezdbus.client module

BLE Client for BlueZ on Linux

class bleak.backends.bluezdbus.client.BleakClientBlueZDBus(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)[source]

Bases: bleak.backends.client.BaseBleakClient

A native Linux Bleak Client

Implemented by using the BlueZ DBUS API.

Parameters

address_or_ble_device (BLEDevice or str) – The Bluetooth address of the BLE peripheral to connect to or the BLEDevice object representing it.

Keyword Arguments
  • timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.

  • disconnected_callback (callable) – Callback that will be scheduled in the event loop when the client is disconnected. The callable must take one argument, which will be this client object.

  • adapter (str) – Bluetooth adapter to use for discovery.

async connect(**kwargs) bool[source]

Connect to the specified GATT server.

Keyword Arguments

timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.

Returns

Boolean representing connection status.

Raises
  • BleakError – If the device is already connected or if the device could not be found.

  • BleakDBusError – If there was a D-Bus error

  • asyncio.TimeoutError – If the connection timed out

async disconnect() bool[source]

Disconnect from the specified GATT server.

Returns

Boolean representing if device is disconnected.

Raises
  • BleakDBusError – If there was a D-Bus error

  • asyncio.TimeoutError if the device was not disconnected within 10 seconds

async get_services(**kwargs) bleak.backends.service.BleakGATTServiceCollection[source]

Get all services registered for this GATT server.

Returns

A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

property is_connected: bool

Check connection status between this client and the server.

Returns

Boolean representing connection status.

property mtu_size: int

Get ATT MTU size for active connection

async pair(*args, **kwargs) bool[source]

Pair with the peripheral.

You can use ConnectDevice method if you already know the MAC address of the device. Else you need to StartDiscovery, Trust, Pair and Connect in sequence.

Returns

Boolean regarding success of pairing.

async read_gatt_char(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID], **kwargs) bytearray[source]

Perform read operation on the specified GATT characteristic.

Parameters

char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.

Returns

(bytearray) The read data.

async read_gatt_descriptor(handle: int, **kwargs) bytearray[source]

Perform read operation on the specified GATT descriptor.

Parameters

handle (int) – The handle of the descriptor to read from.

Returns

(bytearray) The read data.

async start_notify(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) None[source]

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be a integer handle of the characteristic generating the data and the second will be a bytearray containing the data sent from the connected server.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)
Parameters
  • char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.

  • callback (function) – The function to be called on notification.

async stop_notify(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID]) None[source]

Deactivate notification/indication on a specified characteristic.

Parameters

char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.

async unpair() bool[source]

Unpair with the peripheral.

Returns

Boolean regarding success of unpairing.

async write_gatt_char(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID], data: Union[bytes, bytearray, memoryview], response: bool = False) None[source]

Perform a write operation on the specified GATT characteristic.

Note

The version check below is for the “type” option to the “Characteristic.WriteValue” method that was added to Bluez in 5.51 Before that commit, Characteristic.WriteValue was only “Write with response”. Characteristic.AcquireWrite was added in Bluez 5.46 which can be used to “Write without response”, but for older versions of Bluez, it is not possible to “Write without response”.

Parameters
  • char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.

  • data (bytes or bytearray) – The data to send.

  • response (bool) – If write-with-response operation should be done. Defaults to False.

async write_gatt_descriptor(handle: int, data: Union[bytes, bytearray, memoryview]) None[source]

Perform a write operation on the specified GATT descriptor.

Parameters
  • handle (int) – The handle of the descriptor to read from.

  • data (bytes or bytearray) – The data to send.

bleak.backends.bluezdbus.defs module

bleak.backends.bluezdbus.descriptor module

class bleak.backends.bluezdbus.descriptor.BleakGATTDescriptorBlueZDBus(obj: dict, object_path: str, characteristic_uuid: str, characteristic_handle: int)[source]

Bases: bleak.backends.descriptor.BleakGATTDescriptor

GATT Descriptor implementation for BlueZ DBus backend

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 handle: int

Integer handle for this descriptor

property path: str

The DBus path. Mostly needed by bleak, not by end user

property uuid: str

UUID for this descriptor

bleak.backends.bluezdbus.scanner module

class bleak.backends.bluezdbus.scanner.BleakScannerBlueZDBus(**kwargs)[source]

Bases: bleak.backends.scanner.BaseBleakScanner

The native Linux Bleak BLE Scanner.

For possible values for filters, see the parameters to the SetDiscoveryFilter method in the BlueZ docs

Parameters
  • **detection_callback (callable or coroutine) – Optional function that will be called each time a device is discovered or advertising data has changed.

  • **service_uuids (List[str]) – Optional list of service UUIDs to filter on. Only advertisements containing this advertising data will be received. Specifying this also enables scanning while the screen is off on Android.

  • **adapter (str) – Bluetooth adapter to use for discovery.

  • **filters (dict) – A dict of filters to be applied on discovery.

property discovered_devices: List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

Returns

A list of the devices that the scanner has discovered during the scanning.

set_scanning_filter(**kwargs)[source]

Sets OS level scanning filters for the BleakScanner.

For possible values for filters, see the parameters to the SetDiscoveryFilter method in the BlueZ docs

See variant types here: <https://python-dbus-next.readthedocs.io/en/latest/type-system/>

Keyword Arguments

filters (dict) – A dict of filters to be applied on discovery.

async start()[source]

Start scanning for devices

async stop()[source]

Stop scanning for devices

bleak.backends.bluezdbus.service module

class bleak.backends.bluezdbus.service.BleakGATTServiceBlueZDBus(obj, path)[source]

Bases: bleak.backends.service.BleakGATTService

GATT Service implementation for the BlueZ DBus backend

add_characteristic(characteristic: bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus)[source]

Add a BleakGATTCharacteristicBlueZDBus to the service.

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

property characteristics: List[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus]

List of characteristics for this service

property handle: int

The integer handle of this service

property path

The DBus path. Mostly needed by bleak, not by end user

property uuid: str

The UUID to this service

bleak.backends.bluezdbus.signals module

exception bleak.backends.bluezdbus.signals.InvalidMessageTypeError(type)[source]

Bases: TypeError

class bleak.backends.bluezdbus.signals.MatchRules(type: str = 'signal', sender: Optional[str] = None, interface: Optional[str] = None, member: Optional[str] = None, path: Optional[str] = None, path_namespace: Optional[str] = None, destination: Optional[str] = None, arg0namespace: Optional[str] = None, **kwargs)[source]

Bases: object

D-Bus signal match rules.

static parse(rules: str)[source]
bleak.backends.bluezdbus.signals.add_match(bus: dbus_next.aio.message_bus.MessageBus, rules: bleak.backends.bluezdbus.signals.MatchRules) Coroutine[Any, Any, dbus_next.message.Message][source]

Calls org.freedesktop.DBus.AddMatch using rules.

bleak.backends.bluezdbus.signals.assert_bus_name_valid(type: str)[source]

Raise an error if this is not a valid message type.

Parameters

type – The message type to validate.

Raises
  • InvalidBusNameError - If this is not a valid message type.

bleak.backends.bluezdbus.signals.is_message_type_valid(type: str) bool[source]

Whether this is a valid message type.

Parameters

type – The message type to validate.

Returns

Whether the name is a valid message type.

Return type

bool

bleak.backends.bluezdbus.signals.remove_match(bus: dbus_next.aio.message_bus.MessageBus, rules: bleak.backends.bluezdbus.signals.MatchRules) Coroutine[Any, Any, dbus_next.message.Message][source]

Calls org.freedesktop.DBus.RemoveMatch using rules.

bleak.backends.bluezdbus.utils module

bleak.backends.bluezdbus.utils.assert_reply(reply: dbus_next.message.Message)[source]

Checks that a D-Bus message is a valid reply.

Raises
  • BleakDBusError – if the message type is MessageType.ERROR

  • AssentationError – if the message type is not MessageType.METHOD_RETURN

bleak.backends.bluezdbus.utils.extract_service_handle_from_path(path)[source]
bleak.backends.bluezdbus.utils.unpack_variants(dictionary: Dict[str, dbus_next.signature.Variant]) Dict[str, Any][source]

Recursively unpacks all Variant types in a dictionary to their corresponding Python types.

dbus-next doesn’t automatically do this, so this needs to be called on all dictionaries (“a{sv}”) returned from D-Bus messages.

bleak.backends.bluezdbus.utils.validate_address(address)[source]

Module contents

bleak.backends.bluezdbus.check_bluez_version(major: int, minor: int) bool[source]

Checks the BlueZ version.

Returns

True if the BlueZ major version is equal to major and the minor version is greater than or equal to minor, otherwise False.