# 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)

  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

    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() → None

    Start scanning for devices

  async stop() → None

    Stop scanning for devices

### 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)

  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.

  async connect(pair: bool, dangerous_use_bleak_cache: bool = False, **kwargs: Any) → None

    Connect to the specified GATT server.

    Keyword Arguments:

      timeout (float) – Timeout for required `BleakScanner.find_device_by_address` call.

    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

    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

  property name: str

    See `bleak.BleakClient.name()`.

  async pair(*args: Any, **kwargs: Any) → None

    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

    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

    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

    Activate notifications/indications on a characteristic.

  async stop_notify(characteristic: BleakGATTCharacteristic) → None

    Deactivate notification/indication on a specified characteristic.

    Parameters:

      characteristic (BleakGATTCharacteristic) – The characteristic to deactivate notification/indication on.

  async unpair() → None

    Unpair with the peripheral.

  async write_gatt_char(characteristic: BleakGATTCharacteristic, data: SizedBuffer, response: bool) → None

    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: SizedBuffer) → None

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