Linux backend
The Linux backend of Bleak communicates with BlueZ over DBus. Communication uses the dbus-fast package for async access to DBus messaging.
Resolving services with get_services
By default, calling get_services
will wait for services to be resolved
before returning the BleakGATTServiceCollection
. If a previous connection
to the device was made, passing the dangerous_use_bleak_cache
argument will
return the cached services without waiting for them to be resolved again. This
is useful when you know services have not changed, and you want to use the
services immediately, but don’t want to wait for them to be resolved again.
Parallel Access
Each Bleak object should be created and used from a single asyncio event
loop. Simple asyncio programs will only have a single event loop. It’s also
possible to use Bleak with multiple event loops, even at the same time, but
individual Bleak objects should not be shared between event loops. Otherwise,
RuntimeErrors similar to [...] got Future <Future pending> attached to a
different loop
will be thrown.
D-Bus Authentication
Connecting to the host DBus from within a user namespace will fail. This is because the remapped UID will not match the UID that the hosts sees. To work around this, you can hardcode a UID with the BLEAK_DBUS_AUTH_UID environment variable.
API
Scanner
- class bleak.backends.bluezdbus.scanner.BleakScannerBlueZDBus(detection_callback: Callable[[BLEDevice, AdvertisementData], Coroutine[Any, Any, None] | None] | None, service_uuids: list[str] | None, scanning_mode: Literal['active', 'passive'], *, bluez: BlueZScannerArgs, **kwargs: Any)[source]
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 – Optional function that will be called each time a device is discovered or advertising data has changed.
service_uuids – 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.
scanning_mode – Set to
"passive"
to avoid the"active"
scanning mode.**bluez – Dictionary of arguments specific to the BlueZ backend.
**adapter (str) – Bluetooth adapter to use for discovery.
- set_scanning_filter(**kwargs: Any) None [source]
Sets OS level scanning filters for the BleakScanner.
For possible values for filters, see the parameters to the
SetDiscoveryFilter
method in the BlueZ docsSee 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.
Client
BLE Client for BlueZ on Linux
- class bleak.backends.bluezdbus.client.BleakClientBlueZDBus(address_or_ble_device: BLEDevice | str, services: set[str] | None = None, **kwargs: Any)[source]
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.
services – Optional list of service UUIDs that will be used.
- 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(pair: bool, dangerous_use_bleak_cache: bool = False, **kwargs: Any) None [source]
Connect to the specified GATT server.
- Keyword Arguments:
timeout (float) – Timeout for required
BleakScanner.find_device_by_address
call. Defaults to 10.0.- 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() None [source]
Disconnect from the specified GATT server.
- Raises:
BleakDBusError – If there was a D-Bus error
asyncio.TimeoutError if the device was not disconnected within 10 seconds –
- 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: Any, **kwargs: Any) None [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.
- async read_gatt_char(characteristic: BleakGATTCharacteristic, **kwargs: Any) bytearray [source]
Perform read operation on the specified GATT characteristic.
- Parameters:
characteristic (BleakGATTCharacteristic) – The characteristic to read from.
- Returns:
(bytearray) The read data.
- async read_gatt_descriptor(descriptor: BleakGATTDescriptor, **kwargs: Any) bytearray [source]
Perform read operation on the specified GATT descriptor.
- Parameters:
descriptor – The descriptor to read from.
- Returns:
The read data.
- async start_notify(characteristic: BleakGATTCharacteristic, callback: Callable[[bytearray], None], **kwargs: Any) None [source]
Activate notifications/indications on a characteristic.
- async stop_notify(characteristic: BleakGATTCharacteristic) None [source]
Deactivate notification/indication on a specified characteristic.
- Parameters:
characteristic (BleakGATTCharacteristic) – The characteristic to deactivate notification/indication on.
- async write_gatt_char(characteristic: BleakGATTCharacteristic, data: Buffer, response: bool) None [source]
Perform a write operation on the specified GATT characteristic.
- Parameters:
characteristic – The characteristic to write to.
data – The data to send.
response – If write-with-response operation should be done.
- async write_gatt_descriptor(descriptor: BleakGATTDescriptor, data: Buffer) None [source]
Perform a write operation on the specified GATT descriptor.
- Parameters:
handle – The handle of the descriptor to read from.
data – The data to send (any bytes-like object).