Windows backend

The Windows backend of bleak is written using the Bleak WinRT package to provide bindings for the Windows Runtime (WinRT).

The Windows backend implements a BleakClient in the module bleak.backends.winrt.client, a BleakScanner method in the bleak.backends.winrt.scanner module. There are also backend-specific implementations of the BleakGATTService, BleakGATTCharacteristic and BleakGATTDescriptor classes.

Specific features for the Windows backend

Client

• The constructor keyword address_type which can have the values "public" or "random". This value makes sure that the connection is made in a fashion that suits the peripheral.

API

Scanner

class bleak.backends.winrt.scanner.BleakScannerWinRT(detection_callback: Optional[Callable[[BLEDevice, AdvertisementData], Optional[Awaitable[None]]]], service_uuids: Optional[List[str]], scanning_mode: Literal['active', 'passive'], **kwargs)

The native Windows Bleak BLE Scanner.

Implemented using Python/WinRT.

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.

• scanning_mode – Set to "passive" to avoid the "active" scanning mode.

seen_devices: Dict[str, Tuple[BLEDevice, AdvertisementData]]

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

This map must be cleared when scanning starts.

set_scanning_filter(**kwargs) → None

Set a scanning filter for the BleakScanner.

Keyword Arguments

• SignalStrengthFilter (Windows.Devices.Bluetooth.BluetoothSignalStrengthFilter) – A BluetoothSignalStrengthFilter object used for configuration of Bluetooth LE advertisement filtering that uses signal strength-based filtering.

• AdvertisementFilter (Windows.Devices.Bluetooth.Advertisement.BluetoothLEAdvertisementFilter) – A BluetoothLEAdvertisementFilter object used for configuration of Bluetooth LE advertisement filtering that uses payload section-based filtering.

async start() → None

Start scanning for devices

async stop() → None

Stop scanning for devices

Client

BLE Client for Windows 10 systems, implemented with WinRT.

Created on 2020-08-19 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.winrt.client.BleakClientWinRT(address_or_ble_device: Union[BLEDevice, str], services: Optional[Set[str]] = None, *, winrt: WinRTClientArgs, **kwargs)

Native Windows Bleak Client.

Parameters

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

• services – Optional set of service UUIDs that will be used.

• winrt (dict) – A dictionary of Windows-specific configuration values.

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

async connect(**kwargs) → bool

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.

async disconnect() → bool

Disconnect from the specified GATT server.

Returns

Boolean representing if device is disconnected.

async get_services(*, service_cache_mode: Optional[bleak_winrt.windows.devices.bluetooth.BluetoothCacheMode] = None, cache_mode: Optional[bleak_winrt.windows.devices.bluetooth.BluetoothCacheMode] = None, **kwargs) → BleakGATTServiceCollection

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(protection_level: Optional[int] = None, **kwargs) → bool

Attempts to pair with the device.

Keyword Arguments

protection_level (int) –

A DevicePairingProtectionLevel enum value:

1. None - Pair the device using no levels of protection.

2. Encryption - Pair the device using encryption.

3. EncryptionAndAuthentication - Pair the device using encryption and authentication. (This will not work in Bleak…)

Returns

Boolean regarding success of pairing.

async read_gatt_char(char_specifier: Union[BleakGATTCharacteristic, int, str, UUID], **kwargs) → bytearray

Perform read operation on the specified GATT characteristic.

Parameters

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

Keyword Arguments

use_cached (bool) – False forces Windows to read the value from the device again and not use its own cached value. Defaults to False.

Returns

(bytearray) The read data.

async read_gatt_descriptor(handle: int, **kwargs) → bytearray

Perform read operation on the specified GATT descriptor.

Parameters

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

Keyword Arguments

use_cached (bool) – False forces Windows to read the value from the device again and not use its own cached value. Defaults to False.

Returns

(bytearray) The read data.

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

Activate notifications/indications on a characteristic.

Keyword Arguments

force_indicate (bool) – If this is set to True, then Bleak will set up a indication request instead of a notification request, given that the characteristic supports notifications as well as indications.

async stop_notify(char_specifier: Union[BleakGATTCharacteristic, int, str, UUID]) → None

Deactivate notification/indication on a specified characteristic.

Parameters

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

async unpair() → bool

Attempts to unpair from the device.

N.B. unpairing also leads to disconnection in the Windows backend.

Returns

Boolean on whether the unparing was successful.

async write_gatt_char(char_specifier: Union[BleakGATTCharacteristic, int, str, UUID], data: Union[bytes, bytearray, memoryview], response: bool = False) → None

Perform a write operation of the specified GATT characteristic.

Parameters

• char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic 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

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.

class bleak.backends.winrt.client.FutureLike(op: bleak_winrt.windows.foundation.IAsyncOperation)

Wraps a WinRT IAsyncOperation in a “future-like” object so that it can be passed to Python APIs.

Needed until https://github.com/pywinrt/pywinrt/issues/14

class bleak.backends.winrt.client.WinRTClientArgs

Windows-specific arguments for BleakClient.

address_type: Literal['public', 'random']

Can either be "public" or "random", depending on the required address type needed to connect to your device.

use_cached_services: bool

True allows Windows to fetch the services, characteristics and descriptors from the Windows cache instead of reading them from the device. Can be very much faster for known, unchanging devices, but not recommended for DIY peripherals where the GATT layout can change between connections.

False will force the attribute database to be read from the remote device instead of using the OS cache.

If omitted, the OS Bluetooth stack will do what it thinks is best.