Backend implementations

Bleak supports the following operating systems:

• Windows 10, version 16299 (Fall Creators Update) and greater

• Linux distributions with BlueZ >= 5.55 (See Linux backend for more details)

• OS X/macOS support via Core Bluetooth API, from at least version 10.15

• Partial Android support mostly using Python-for-Android/Kivy.

• Partial, optional iOS support using Pythonista iOS app.

These pages document platform specific differences from the interface API.

Contents:

• Windows backend
  • Specific features for the Windows backend
  • API
• Linux backend
  • Resolving services with get_services
  • Parallel Access
  • D-Bus Authentication
  • API
• macOS backend
  • Specific features for the macOS backend
  • API
• Android backend
  • Considerations on Android
  • API
• Pythonista iOS app backend
  • Optional installation with Bleak
  • Pairing
  • Characteristic descriptors
  • Notifications

Backend selection

Communicating with Bluetooth hardware requires calling OS-specific APIs. These are abstracted as “backends” in Bleak.

The backend will be automatically selected based on the operating system Bleak is running on. In some cases, this may also depend on a specific runtime, like Pythonista on iOS.

class bleak.backends.BleakBackend(*values)

Identifiers for available built-in Bleak backends.

Added in version 2.0.

BLUEZ_DBUS = 'bluez_dbus'

BlueZ D-Bus backend for Linux.

CORE_BLUETOOTH = 'core_bluetooth'

CoreBluetooth backend for macOS.

P4ANDROID = 'p4android'

Python for Android backend.

PYTHONISTA_CB = 'pythonista_cb'

Pythonista CoreBluetooth backend for iOS and macOS.

WIN_RT = 'win_rt'

Windows Runtime backend for Windows.

bleak.backends.get_default_backend() → BleakBackend

Returns the preferred backend for the current platform/environment.

Added in version 2.0.

Shared Backend API

Warning

The backend APIs are not considered part of the stable API and may change without notice.

Scanner

class bleak.backends.scanner.AdvertisementData(local_name: str | None, manufacturer_data: dict[int, bytes], service_data: dict[str, bytes], service_uuids: list[str], tx_power: int | None, rssi: int, platform_data: tuple[Any, ...])

Wrapper around the advertisement data that each platform returns upon discovery

local_name: str | None

The local name of the device or None if not included in advertising data.

manufacturer_data: dict[int, bytes]

Dictionary of manufacturer data in bytes from the received advertisement data or empty dict if not present.

The keys are Bluetooth SIG assigned Company Identifiers and the values are bytes.

https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/

platform_data: tuple[Any, ...]

Tuple of platform specific data.

This is not a stable API. The actual values may change between releases.

rssi: int

The Radio Receive Signal Strength (RSSI) in dBm.

Added in version 0.19.

service_data: dict[str, bytes]

Dictionary of service data from the received advertisement data or empty dict if not present.

service_uuids: list[str]

List of service UUIDs from the received advertisement data or empty list if not present.

tx_power: int | None

TX Power Level of the remote device from the received advertising data or None if not present.

Added in version 0.17.

bleak.backends.scanner.AdvertisementDataCallback

Type alias for callback called when advertisement data is received.

alias of Callable[[BLEDevice, AdvertisementData], Coroutine[Any, Any, None] | None]

bleak.backends.scanner.AdvertisementDataFilter

Type alias for an advertisement data filter function.

Implementations should return True for matches, otherwise False.

alias of Callable[[BLEDevice, AdvertisementData], bool]

class bleak.backends.scanner.BaseBleakScanner(detection_callback: Callable[[BLEDevice, AdvertisementData], Coroutine[Any, Any, None] | None] | None, service_uuids: list[str] | None)

Interface for Bleak Bluetooth LE Scanners

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.

call_detection_callbacks(device: BLEDevice, advertisement_data: AdvertisementData) → None

Calls all registered detection callbacks.

Backend implementations should call this method when an advertisement event is received from the OS.

create_or_update_device(key: str, address: str, name: str | None, details: Any, adv: AdvertisementData) → BLEDevice

Creates or updates a device in seen_devices.

Parameters:

• key – A backend-specific identifier for the device.

• address – The Bluetooth address of the device (UUID on macOS).

• name – The OS display name for the device.

• details – The platform-specific handle for the device.

• adv – The most recent advertisement data received.

Returns:

The updated device.

is_allowed_uuid(service_uuids: list[str] | None) → bool

Check if the advertisement data contains any of the service UUIDs matching the filter. If no filter is set, this will always return True.

Parameters:

service_uuids – The service UUIDs from the advertisement data.

Returns:

True if the advertisement data should be allowed or False

if the advertisement data should be filtered out.

register_detection_callback(callback: Callable[[BLEDevice, AdvertisementData], Coroutine[Any, Any, None] | None] | None) → Callable[[], None]

Register a callback that is called when an advertisement event from the OS is received.

The callback is a function or coroutine that takes two arguments: BLEDevice and AdvertisementData.

Parameters:

callback – A function, coroutine or None.

Returns:

A method that can be called to unregister the callback.

seen_devices: dict[str, tuple[BLEDevice, AdvertisementData]]

Map of device identifier to BLEDevice and most recent advertisement data.

The key is a backend-specific identifier for the device.

This map must be cleared when scanning starts.

abstractmethod async start() → None

Start scanning for devices

abstractmethod async stop() → None

Stop scanning for devices

bleak.backends.scanner.get_platform_scanner_backend_type() → tuple[type[BaseBleakScanner], BleakBackend]

Gets the platform-specific BaseBleakScanner type.

Client

Base class for backend clients.

class bleak.backends.client.BaseBleakClient(address_or_ble_device: BLEDevice | str, **kwargs: Any)

The Client Interface for Bleak Backend implementations to implement.

The documentation of this interface should thus be safe to use as a reference for your implementation.

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

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

abstractmethod async connect(pair: bool, **kwargs: Any) → None

Connect to the specified GATT server.

Parameters:

• pair (bool) – If the client should attempt to pair with the

• paired. (peripheral before connecting if it is not already)

• appropriate (Backends that can't implement this should make an)

• parameter. (log message and ignore the)

abstractmethod async disconnect() → None

Disconnect from the specified GATT server.

abstract property is_connected: bool

Check connection status between this client and the server.

Returns:

Boolean representing connection status.

abstract property mtu_size: int

Gets the negotiated MTU.

property name: str

See bleak.BleakClient.name().

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

Pair with the peripheral.

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

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

set_disconnected_callback(callback: Callable[[], None] | None, **kwargs: Any) → None

Set the disconnect callback. The callback will only be called on unsolicited disconnect event.

Set the callback to None to remove any existing callback.

Parameters:

callback – callback to be called on disconnection.

abstractmethod async start_notify(characteristic: BleakGATTCharacteristic, callback: Callable[[bytearray], None], **kwargs: Any) → None

Activate notifications/indications on a characteristic.

Implementers should call the OS function to enable notifications or indications on the characteristic.

To keep things the same cross-platform, notifications should be preferred over indications if possible when a characteristic supports both.

abstractmethod async stop_notify(characteristic: BleakGATTCharacteristic) → None

Deactivate notification/indication on a specified characteristic.

Parameters:

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

abstractmethod async unpair() → None

Unpair with the peripheral.

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

abstractmethod async write_gatt_descriptor(descriptor: BleakGATTDescriptor, data: SizedBuffer) → None

Perform a write operation on the specified GATT descriptor.

Parameters:

• descriptor – The descriptor to read from.

• data – The data to send (any bytes-like object).

bleak.backends.client.get_platform_client_backend_type() → tuple[type[BaseBleakClient], BleakBackend]

Gets the platform-specific BaseBleakClient type.