bleak.backends.android package

Submodules

bleak.backends.android.adapter module

class bleak.backends.android.adapter.BleakAdapterAndroid(manager: android.bluetooth.BluetoothManager)

Bases: BaseBleakAdapter

The Android Bleak BLE Adapter using Chaquopy/BeeWare.

async classmethod get(**kwargs: Any) → Self

Get a Bluetooth adapter for the current platform.

Returns:

A platform-specific BaseBleakAdapter instance.

Raises:

NotImplementedError – if the current backend does not support this.

async get_connected_devices(service_uuids: frozenset[str]) → list[BLEDevice]

Retrieve BLE devices that are currently connected to the system.

Parameters:

service_uuids – Service UUIDs to filter on.

Returns:

A list of BLEDevice for each connected BLE device.

Raises:

NotImplementedError – if the current backend does not support this.

bleak.backends.android.broadcast module

class bleak.backends.android.broadcast.BroadcastReceiver(*args: Any, **kwargs: Any)

Bases: static_proxy

onReceive(context: android.content.Context, intent: android.content.Intent)

start()

stop()

bleak.backends.android.client module

class bleak.backends.android.client.BleakClientAndroid(address_or_ble_device: BLEDevice | str, services: set[UUID] | None, *, disconnected_callback: Callable[[], None] | None, timeout: float, **kwargs: Any)

Bases: BaseBleakClient

Android Bleak Client using Chaquopy/BeeWare.

Parameters:

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

• services – Optional set of services UUIDs to filter.

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

Connect to the specified GATT server.

async disconnect() → None

Disconnect from the specified GATT server.

property is_connected: bool

Check connection status between this client and the server.

Returns:

Boolean representing connection status.

property mtu_size: int

Gets the negotiated MTU.

property name: str

See bleak.BleakClient.name().

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

Pair with the peripheral.

async read_gatt_char(characteristic: BleakGATTCharacteristic, *, use_cached: bool = False, **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, *, use_cached: bool = False, **kwargs: Any) → bytearray

Perform read operation on the specified GATT descriptor.

Parameters:

• descriptor – The descriptor to read from.

• use_cached – Whether to use cached value.

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:

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

class bleak.backends.android.client.ConnectObjects(adapter: 'BluetoothAdapter', device: 'BluetoothDevice', gatt: 'BluetoothGatt', callbacks: 'PythonBluetoothGattCallback', subscriptions: 'dict[int, NotifyCallback]')

Bases: object

adapter: android.bluetooth.BluetoothAdapter

callbacks: PythonBluetoothGattCallback

device: android.bluetooth.BluetoothDevice

gatt: android.bluetooth.BluetoothGatt

subscriptions: dict[int, Callable[[bytearray], None]]

bleak.backends.android.client_callback module

class bleak.backends.android.client_callback.OnCharacteristicReadCallback(handle: 'int')

Bases: CallbackApi[OnCharacteristicReadResult]

handle: int

class bleak.backends.android.client_callback.OnCharacteristicReadResult(value: 'bytes')

Bases: CallbackResult

value: bytes

class bleak.backends.android.client_callback.OnCharacteristicWriteCallback(handle: 'int')

Bases: CallbackApi[EmptyCallbackResult]

handle: int

class bleak.backends.android.client_callback.OnConnectionStateChangeCallback

Bases: CallbackApi[OnConnectionStateChangeResult]

class bleak.backends.android.client_callback.OnConnectionStateChangeResult(new_state: 'int')

Bases: CallbackResult

new_state: int

class bleak.backends.android.client_callback.OnDescriptorReadCallback(uuid: 'str')

Bases: CallbackApi[OnDescriptorReadResult]

uuid: str

class bleak.backends.android.client_callback.OnDescriptorReadResult(value: 'bytes')

Bases: CallbackResult

value: bytes

class bleak.backends.android.client_callback.OnDescriptorWriteCallback(uuid: 'str')

Bases: CallbackApi[EmptyCallbackResult]

uuid: str

class bleak.backends.android.client_callback.OnMtuChangedCallback

Bases: CallbackApi[OnMtuChangedResult]

class bleak.backends.android.client_callback.OnMtuChangedResult(mtu: 'int')

Bases: CallbackResult

mtu: int

class bleak.backends.android.client_callback.OnServicesDiscoveredCallback

Bases: CallbackApi[EmptyCallbackResult]

class bleak.backends.android.client_callback.PythonBluetoothGattCallback(*args: Any, **kwargs: Any)

Bases: static_proxy

Callback class for GattClient. PRIVATE.

onCharacteristicWrite(gatt: android.bluetooth.BluetoothGatt, characteristic: android.bluetooth.BluetoothGattCharacteristic, status: int)

onConnectionStateChange(gatt: android.bluetooth.BluetoothGatt, status: int, newState: int)

onDescriptorWrite(gatt: android.bluetooth.BluetoothGatt, descriptor: android.bluetooth.BluetoothGattDescriptor, status: int)

onMtuChanged(gatt: android.bluetooth.BluetoothGatt, mtu: int, status: int)

onServicesDiscovered(gatt: android.bluetooth.BluetoothGatt, status: int)

bleak.backends.android.dispatcher module

class bleak.backends.android.dispatcher.CallbackApi

Bases: Generic[CallbackResultT]

class bleak.backends.android.dispatcher.CallbackDispatcher(loop: AbstractEventLoop)

Bases: object

dispatch(dispatch_func: Callable[[], T], callback_api: CallbackApi[CallbackResultT]) → tuple[T, Future[CallbackResultT]]

Register the callback future and invoke dispatch_func synchronously.

Returns the future to await for the callback result (and optionally the dispatch result as the first element of a tuple if return_dispatch_result=True). Prefer perform_and_wait() for the common case. Use this method directly when you need the future even if the await fails (e.g. for cleanup on timeout).

The dispatch_func must raise BleakError on failure.

fail_all_threadsafe(exception: Exception) → None

Fails all pending futures with exception.

This is needed when Android won’t call the callbacks anymore, e.g. after the device disconnected.

futures: dict[CallbackApi[Any], Future[Any]]

async perform_and_wait(dispatch_func: Callable[[], T], callback_api: CallbackApi[CallbackResultT]) → tuple[T, CallbackResultT]

Perform an API call and wait for the callback result.

Parameters:

• dispatch_func – The API function to call, that triggers the callback. Must raise BleakError on failure.

• callback_api – The callback to wait for to get the result.

Returns:

Tuple of (dispatch result, callback result).

result_state_threadsafe(failure: Exception | None, callback_api: CallbackApi[CallbackResultT], callback_result: CallbackResultT)

states: dict[CallbackApi[Any], CallbackState]

class bleak.backends.android.dispatcher.CallbackResult

Bases: object

class bleak.backends.android.dispatcher.CallbackState(failure: 'Exception | None', callback_result: 'CallbackResult')

Bases: object

callback_result: CallbackResult

failure: Exception | None

class bleak.backends.android.dispatcher.EmptyCallbackResult

Bases: CallbackResult

bleak.backends.android.permissions module

async bleak.backends.android.permissions.check_for_permissions(loop: AbstractEventLoop)

bleak.backends.android.scanner module

class bleak.backends.android.scanner.BleakScannerAndroid(detection_callback: Callable[[BLEDevice, AdvertisementData], Coroutine[Any, Any, None] | None] | None, service_uuids: list[str] | None, scanning_mode: Literal['active', 'passive'], **kwargs: Any)

Bases: BaseBleakScanner

Android Bleak BLE Scanner using Chaquopy/BeeWare.

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.

handle_scan_result(result: android.bluetooth.le.ScanResult) → None

async start() → None

Start scanning for devices

async stop() → None

Stop scanning for devices

class bleak.backends.android.scanner.ExcessiveUsageChecker

Bases: object

On Android, no more than 5 start/stop scanning operations are allowed per 30 seconds!

Before API level 33, Android does not report an error when this limit is exceeded, scanning just silently doesn’t work. This is a helper class to track scan start times so that we can raise an error instead.

See this commit: https://android-review.googlesource.com/c/platform/packages/apps/Bluetooth/+/215844 Or this comment: https://github.com/NordicSemiconductor/Android-Scanner-Compat-Library/issues/18#issuecomment-402412139

add_new_scan() → None

Record a new scan start time.

check() → None

Raise BleakError if starting a scan now would exceed the limit.

time_until_next_scan_allowed() → float

Get the time in seconds until the next scan may be started (0 if it can be started now).

class bleak.backends.android.scanner.ScanObjects(adapter: 'BluetoothAdapter', javascanner: 'BluetoothLeScanner', callback: 'PythonScanCallback')

Bases: object

adapter: android.bluetooth.BluetoothAdapter

callback: PythonScanCallback

javascanner: android.bluetooth.le.BluetoothLeScanner

bleak.backends.android.scanner_callback module

class bleak.backends.android.scanner_callback.OnScanCallback

Bases: CallbackApi[OnScanResult]

class bleak.backends.android.scanner_callback.OnScanResult(result: "'None | ScanResult'")

Bases: CallbackResult

result: None | ScanResult

class bleak.backends.android.scanner_callback.PythonScanCallback(*args: Any, **kwargs: Any)

Bases: static_proxy

Callback class for LE Scan. PRIVATE.

This class holds methods that receive and handle data from Android’s BluetoothLeScanner methods. It is not intended to call this class directly.

onScanFailed(errorCode: int)

onScanResult(callbackType: int, result: android.bluetooth.le.ScanResult)

bleak.backends.android.status module

class bleak.backends.android.status.ScanFailed(*values)

Bases: IntEnum

ALREADY_STARTED = 1

APPLICATION_REGISTRATION_FAILED = 2

FEATURE_UNSUPPORTED = 4

INTERNAL_ERROR = 3

SCAN_FAILED_OUT_OF_HARDWARE_RESOURCES = 5

SCAN_FAILED_SCANNING_TOO_FREQUENTLY = 6

bleak.backends.android.utils module

bleak.backends.android.utils.iterate_java_obj(java_iterable: java.lang.Iterable.~T) → Iterator[T]

Module contents