Interfaces, exceptions and utils

Connection Clients

Interface

Base class for backend clients.

Created on 2018-04-23 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.client.BaseBleakClient(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)

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

connect(**kwargs) → bool

Connect to the specified GATT server.

Returns:Boolean representing connection status.

disconnect() → bool

Disconnect from the specified GATT server.

Returns:Boolean representing connection status.

get_services() → bleak.backends.service.BleakGATTServiceCollection

Get all services registered for this GATT server.

Returns:A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

is_connected() → bool

Check connection status between this client and the server.

Returns:Boolean representing connection status.

pair(*args, **kwargs) → bool

Pair with the peripheral.

read_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.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. Returns:(bytearray) The read data.

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. Returns:(bytearray) The read data.

set_disconnected_callback(callback: Optional[Callable[BaseBleakClient, None]], **kwargs) → None

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

Callbacks must accept one input which is the client object itself.

Set the callback to None to remove any existing callback.

def callback(client):
    print("Client with address {} got disconnected!".format(client.address))

client.set_disconnected_callback(callback)
client.connect()

Parameters:callback – callback to be called on disconnection.

start_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be a integer handle of the characteristic generating the data and the second will be a bytearray.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)

Parameters:

• char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
• callback (function) – The function to be called on notification.

stop_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.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.

unpair() → bool

Unpair with the peripheral.

write_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], data: bytearray, response: bool = False) → None

Perform a write operation on 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.

write_gatt_descriptor(handle: int, data: bytearray) → 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.

Windows

BLE Client for Windows 10 systems.

Created on 2017-12-05 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.dotnet.client.BleakClientDotNet(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)

The native Windows Bleak Client.

Implemented using pythonnet, a package that provides an integration to the .NET Common Language Runtime (CLR). Therefore, much of the code below has a distinct C# feel.

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 BleakScanner.find_device_by_address call. Defaults to 10.0.

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.

disconnect() → bool

Disconnect from the specified GATT server.

Returns:Boolean representing if device is disconnected. Raises:asyncio.TimeoutError – If device did not disconnect with 10 seconds.

get_services() → bleak.backends.service.BleakGATTServiceCollection

Get all services registered for this GATT server.

Returns:A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

is_connected() → bool

Check connection status between this client and the server.

Returns:Boolean representing connection status.

pair(protection_level=None, **kwargs) → bool

Attempts to pair with the device.

Keyword Arguments:  protection_level –

DevicePairingProtectionLevel

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.

Returns:Boolean regarding success of pairing.

read_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], use_cached=False, **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.
• 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.

read_gatt_descriptor(handle: int, use_cached=False, **kwargs) → bytearray

Perform read operation on the specified GATT descriptor.

Parameters:

• handle (int) – The handle of the descriptor to read from.
• 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.

start_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be a integer handle of the characteristic generating the data and the second will be a bytearray containing the data sent from the connected server.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)

Parameters:

• char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
• callback (function) – The function to be called on notification.

stop_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.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.

unpair() → bool

Attempts to unpair from the device.

Returns:Boolean on whether the unparing was successful.

write_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], data: bytearray, 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.

write_gatt_descriptor(handle: int, data: bytearray) → 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.

macOS

BLE Client for CoreBluetooth on macOS

Created on 2019-06-26 by kevincar <kevincarrolldavis@gmail.com>

class bleak.backends.corebluetooth.client.BleakClientCoreBluetooth(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)

CoreBluetooth class interface for BleakClient

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 BleakScanner.find_device_by_address call. Defaults to 10.0.

connect(**kwargs) → bool

Connect to a specified Peripheral

Keyword Arguments:  timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0. Returns:Boolean representing connection status.

disconnect() → bool

Disconnect from the peripheral device

get_rssi() → int

To get RSSI value in dBm of the connected Peripheral

get_services() → bleak.backends.service.BleakGATTServiceCollection

Get all services registered for this GATT server.

Returns:A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

is_connected() → bool

Checks for current active connection

pair(*args, **kwargs) → bool

Attempt to pair with a peripheral.

Note

This is not available on macOS since there is not explicit method to do a pairing, Instead the docs state that it “auto-pairs” when trying to read a characteristic that requires encryption, something Bleak cannot do apparently.

Reference:

• Apple Docs
• Stack Overflow post #1
• Stack Overflow post #2

Returns:Boolean regarding success of pairing.

read_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], use_cached=False, **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.
• use_cached (bool) – False forces macOS to read the value from the device again and not use its own cached value. Defaults to False.

Returns:

(bytearray) The read data.

read_gatt_descriptor(handle: int, use_cached=False, **kwargs) → bytearray

Perform read operation on the specified GATT descriptor.

Parameters:

• handle (int) – The handle of the descriptor to read from.
• 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.

start_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be a integer handle of the characteristic generating the data and the second will be a bytearray containing the data sent from the connected server.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)

Parameters:

• char_specifier (BleakGATTCharacteristic, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristic object representing it.
• callback (function) – The function to be called on notification.

stop_notify(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.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.

unpair() → bool

Returns:

write_gatt_char(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], data: bytearray, 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.

write_gatt_descriptor(handle: int, data: bytearray) → 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.

Linux Distributions with BlueZ

BLE Client for BlueZ on Linux

class bleak.backends.bluezdbus.client.BleakClientBlueZDBus(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)

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. Keyword Arguments:  timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.

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.

disconnect() → bool

Disconnect from the specified GATT server.

Returns:Boolean representing if device is disconnected.

get_all_for_characteristic(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID]) → dict

Get all properties for a characteristic.

This method should generally not be needed by end user, since it is a DBus specific method.

Parameters:char_specifier – The characteristic to get properties for, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it. Returns:(dict) Properties dictionary

get_services() → bleak.backends.service.BleakGATTServiceCollection

Get all services registered for this GATT server.

Returns:A bleak.backends.service.BleakGATTServiceCollection with this device’s services tree.

is_connected() → bool

Check connection status between this client and the server.

Returns:Boolean representing connection status.

pair(*args, **kwargs) → bool

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.

Returns:Boolean regarding success of pairing.

read_gatt_char(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID], **kwargs) → bytearray

Perform read operation on the specified GATT characteristic.

Parameters:char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it. Returns:(bytearray) The read data.

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. Returns:(bytearray) The read data.

start_notify(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None

Activate notifications/indications on a characteristic.

Callbacks must accept two inputs. The first will be a integer handle of the characteristic generating the data and the second will be a bytearray containing the data sent from the connected server.

def callback(sender: int, data: bytearray):
    print(f"{sender}: {data}")
client.start_notify(char_uuid, callback)

Parameters:

• char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.
• callback (function) – The function to be called on notification.

Keyword Arguments:  

notification_wrapper (bool) – Set to False to avoid parsing of notification to bytearray.

stop_notify(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID]) → None

Deactivate notification/indication on a specified characteristic.

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

unpair() → bool

Unpair with the peripheral.

Returns:Boolean regarding success of unpairing.

write_gatt_char(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID], data: bytearray, response: bool = False) → None

Perform a write operation on the specified GATT characteristic.

Note

The version check below is for the “type” option to the “Characteristic.WriteValue” method that was added to Bluez in 5.51 Before that commit, Characteristic.WriteValue was only “Write with response”. Characteristic.AcquireWrite was added in Bluez 5.46 which can be used to “Write without response”, but for older versions of Bluez, it is not possible to “Write without response”.

Parameters:

• char_specifier (BleakGATTCharacteristicBlueZDBus, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicBlueZDBus object representing it.
• data (bytes or bytearray) – The data to send.
• response (bool) – If write-with-response operation should be done. Defaults to False.

write_gatt_descriptor(handle: int, data: bytearray) → 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.

Scanning Clients

Interface

class bleak.backends.scanner.BaseBleakScanner(*args, **kwargs)

Interface for Bleak Bluetooth LE Scanners

classmethod discover(timeout=5.0, **kwargs) → List[bleak.backends.device.BLEDevice]

Scan continuously for timeout seconds and return discovered devices.

Parameters:timeout – Time to scan for. Keyword Arguments:  **kwargs – Implementations might offer additional keyword arguments sent to the constructor of the BleakScanner class.

Returns:

classmethod find_device_by_address(device_identifier: str, timeout: float = 10.0) → bleak.backends.device.BLEDevice

A convenience method for obtaining a BLEDevice object specified by Bluetooth address or (macOS) UUID address.

Parameters:

• device_identifier (str) – The Bluetooth/UUID address of the Bluetooth peripheral sought.
• timeout (float) – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

Returns:

The BLEDevice sought or None if not detected.

get_discovered_devices() → List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

Returns:A list of the devices that the scanner has discovered during the scanning.

register_detection_callback(callback: Callable)

Register a callback that is called when a device is discovered or has a property changed.

set_scanning_filter(**kwargs)

Set scanning filter for the BleakScanner.

Parameters:**kwargs – The filter details. This will differ a lot between backend implementations.

start()

Start scanning for devices

stop()

Stop scanning for devices

Windows

class bleak.backends.dotnet.scanner.BleakScannerDotNet(**kwargs)

The native Windows Bleak BLE Scanner.

Implemented using pythonnet, a package that provides an integration to the .NET Common Language Runtime (CLR). Therefore, much of the code below has a distinct C# feel.

Keyword Arguments:  

• mode (scanning) – Set to Passive to avoid the Active scanning mode.
• 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.

classmethod find_device_by_address(device_identifier: str, timeout: float = 10.0, **kwargs) → Optional[bleak.backends.device.BLEDevice]

A convenience method for obtaining a BLEDevice object specified by Bluetooth address.

Parameters:

• device_identifier (str) – The Bluetooth address of the Bluetooth peripheral.
• timeout (float) – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

Keyword Arguments:  

• mode (scanning) – Set to Passive to avoid the Active scanning mode.
• 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.

Returns:

The BLEDevice sought or None if not detected.

get_discovered_devices() → List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

Returns:A list of the devices that the scanner has discovered during the scanning.

register_detection_callback(callback: Callable)

Set a function to act as Received Event Handler.

Documentation for the Event Handler: https://docs.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.advertisement.bluetoothleadvertisementwatcher.received

Parameters:callback – Function accepting two arguments: sender (Windows.Devices.Bluetooth.AdvertisementBluetoothLEAdvertisementWatcher) and eventargs (Windows.Devices.Bluetooth.Advertisement.BluetoothLEAdvertisementReceivedEventArgs)

set_scanning_filter(**kwargs)

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.

start()

Start scanning for devices

status

Get status of the Watcher.

Returns:Aborted 4 An error occurred during transition or scanning that stopped the watcher due to an error.

Created 0 The initial status of the watcher.

Started 1 The watcher is started.

Stopped 3 The watcher is stopped.

Stopping 2 The watcher stop command was issued.

stop()

Stop scanning for devices

macOS

class bleak.backends.corebluetooth.scanner.BleakScannerCoreBluetooth(**kwargs)

The native macOS Bleak BLE Scanner.

Documentation: https://developer.apple.com/documentation/corebluetooth/cbcentralmanager

CoreBluetooth doesn’t explicitly use Bluetooth addresses to identify peripheral devices because private devices may obscure their Bluetooth addresses. To cope with this, CoreBluetooth utilizes UUIDs for each peripheral. Bleak uses this for the BLEDevice address on macOS.

Keyword Arguments:  timeout (double) – The scanning timeout to be used, in case of missing stopScan_ method.

classmethod find_device_by_address(device_identifier: str, timeout: float = 10.0, **kwargs) → Optional[bleak.backends.device.BLEDevice]

A convenience method for obtaining a BLEDevice object specified by macOS UUID address.

Parameters:

• device_identifier (str) – The Bluetooth address of the Bluetooth peripheral.
• timeout (float) – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

Returns:

The BLEDevice sought or None if not detected.

get_discovered_devices() → List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

Returns:A list of the devices that the scanner has discovered during the scanning.

register_detection_callback(callback: Callable)

Set a function to act as callback on discovered devices or devices with changed properties.

Parameters:callback – Function accepting three arguments: peripheral advertisementData rssi

set_scanning_filter(**kwargs)

Set scanning filter for the scanner.

Note

This is not implemented for macOS yet.

Raises:NotImplementedError

start()

Start scanning for devices

stop()

Stop scanning for devices

Linux Distributions with BlueZ

class bleak.backends.bluezdbus.scanner.BleakScannerBlueZDBus(**kwargs)

The native Linux Bleak BLE Scanner.

For possible values for filters, see the parameters to the SetDiscoveryFilter method in the BlueZ docs

Keyword Arguments:  

• device (str) – Bluetooth device to use for discovery.
• filters (dict) – A dict of filters to be applied on discovery.

classmethod find_device_by_address(device_identifier: str, timeout: float = 10.0, **kwargs) → bleak.backends.device.BLEDevice

A convenience method for obtaining a BLEDevice object specified by Bluetooth address.

Parameters:

• device_identifier (str) – The Bluetooth address of the Bluetooth peripheral.
• timeout (float) – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.

Keyword Arguments:  

device (str) – Bluetooth device to use for discovery.

Returns:

The BLEDevice sought or None if not detected.

get_discovered_devices() → List[bleak.backends.device.BLEDevice]

Gets the devices registered by the BleakScanner.

Returns:A list of the devices that the scanner has discovered during the scanning.

register_detection_callback(callback: Callable)

Set a function to be called on each device discovery by scanner and when a discovered device has a changed property.

Parameters:callback – Function accepting one argument of type txdbus.message.SignalMessage

set_scanning_filter(**kwargs)

Sets OS level scanning filters for the BleakScanner.

For possible values for filters, see the parameters to the SetDiscoveryFilter method in the BlueZ docs

Keyword Arguments:  filters (dict) – A dict of filters to be applied on discovery.

start()

Start scanning for devices

stop()

Stop scanning for devices

Class representing BLE devices

Generated by bleak.discover() and bleak.backends.scanning.BaseBleakScanner.

Wrapper class for Bluetooth LE servers returned from calling bleak.discover().

Created on 2018-04-23 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.device.BLEDevice(address, name, details=None, **kwargs)

A simple wrapper class representing a BLE server detected during a discover call.

• When using Windows backend, details attribute is a Windows.Devices.Bluetooth.Advertisement.BluetoothLEAdvertisement object, unless it is created with the Windows.Devices.Enumeration discovery method, then is is a Windows.Devices.Enumeration.DeviceInformation.
• When using Linux backend, details attribute is a dict with keys path which has the string path to the DBus device object and props which houses the properties dictionary of the D-Bus Device.
• When using macOS backend, details attribute will be a CBPeripheral object.

address = None

The Bluetooth address of the device on this machine.

details = None

The OS native details required for connecting to the device.

metadata = None

Device specific details. Contains a uuids key which is a list of service UUIDs and a manufacturer_data field with a bytes-object from the advertised data.

name = None

The advertised name of the device.

rssi

Get the signal strength in dBm

GATT objects

Gatt Service Collection class and interface class for the Bleak representation of a GATT Service.

Created on 2019-03-19 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.service.BleakGATTService(obj)

Interface for the Bleak representation of a GATT Service.

add_characteristic(characteristic: bleak.backends.characteristic.BleakGATTCharacteristic)

Add a BleakGATTCharacteristic to the service.

Should not be used by end user, but rather by bleak itself.

characteristics

List of characteristics for this service

description

String description for this service

get_characteristic(uuid: Union[str, uuid.UUID]) → Optional[bleak.backends.characteristic.BleakGATTCharacteristic]

Get a characteristic by UUID.

Parameters:uuid – The UUID to match. Returns:The first characteristic matching uuid or None if no matching characteristic was found.

uuid

The UUID to this service

class bleak.backends.service.BleakGATTServiceCollection

Simple data container for storing the peripheral’s service complement.

add_characteristic(characteristic: bleak.backends.characteristic.BleakGATTCharacteristic)

Add a BleakGATTCharacteristic to the service collection.

Should not be used by end user, but rather by bleak itself.

add_descriptor(descriptor: bleak.backends.descriptor.BleakGATTDescriptor)

Add a BleakGATTDescriptor to the service collection.

Should not be used by end user, but rather by bleak itself.

add_service(service: bleak.backends.service.BleakGATTService)

Add a BleakGATTService to the service collection.

Should not be used by end user, but rather by bleak itself.

characteristics

Returns dictionary of handles to BleakGATTCharacteristic

descriptors

Returns a dictionary of integer handles to BleakGATTDescriptor

get_characteristic(specifier: Union[int, str, uuid.UUID]) → bleak.backends.characteristic.BleakGATTCharacteristic

Get a characteristic by handle (int) or UUID (str or uuid.UUID)

get_descriptor(handle: int) → bleak.backends.descriptor.BleakGATTDescriptor

Get a descriptor by integer handle

get_service(_uuid: Union[str, uuid.UUID]) → bleak.backends.service.BleakGATTService

Get a service by UUID string

services

Returns dictionary of UUID strings to BleakGATTService

Interface class for the Bleak representation of a GATT Characteristic

Created on 2019-03-19 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.characteristic.BleakGATTCharacteristic(obj: Any)

Interface for the Bleak representation of a GATT Characteristic

add_descriptor(descriptor: bleak.backends.descriptor.BleakGATTDescriptor)

Add a BleakGATTDescriptor to the characteristic.

Should not be used by end user, but rather by bleak itself.

description

Description for this characteristic

descriptors

List of descriptors for this service

get_descriptor(specifier: Union[int, str, uuid.UUID]) → Optional[bleak.backends.descriptor.BleakGATTDescriptor]

Get a descriptor by handle (int) or UUID (str or uuid.UUID)

handle

The handle for this characteristic

properties

Properties of this characteristic

service_uuid

The UUID of the Service containing this characteristic

uuid

The UUID for this characteristic

class bleak.backends.characteristic.GattCharacteristicsFlags

An enumeration.

Interface class for the Bleak representation of a GATT Descriptor

Created on 2019-03-19 by hbldh <henrik.blidh@nedomkull.com>

class bleak.backends.descriptor.BleakGATTDescriptor(obj: Any)

Interface for the Bleak representation of a GATT Descriptor

characteristic_handle

handle for the characteristic that this descriptor belongs to

characteristic_uuid

UUID for the characteristic that this descriptor belongs to

description

A text description of what this descriptor represents

handle

Integer handle for this descriptor

uuid

UUID for this descriptor

Exceptions

exception bleak.exc.BleakDotNetTaskError

Wrapped exception that occurred in .NET async Task.

exception bleak.exc.BleakError

Base Exception for bleak.

Utilities

bleak.utils.mac_int_2_str(mac)

Convert integer Bluetooth address to colon separated hex string.

Parameters:mac (int) – A positive integer. Returns:Bluetooth address as colon separated hex string.

bleak.utils.mac_str_2_int(mac)

Convert colon separated hex string Bluetooth address to integer.

Parameters:mac (str) – A colon separated hex string Bluetooth address. Returns:Bluetooth address as integer.