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)[source]¶ 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[source]¶ Connect to the specified GATT server.
Returns: Boolean representing connection status.
-
disconnect
() → bool[source]¶ Disconnect from the specified GATT server.
Returns: Boolean representing connection status.
-
get_services
(**kwargs) → bleak.backends.service.BleakGATTServiceCollection[source]¶ Get all services registered for this GATT server.
Returns: A bleak.backends.service.BleakGATTServiceCollection
with this device’s services tree.
-
is_connected
¶ Check connection status between this client and the server.
Returns: Boolean representing connection status.
-
read_gatt_char
(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], **kwargs) → bytearray[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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.
-
write_gatt_char
(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], data: Union[bytes, bytearray, memoryview], response: bool = False) → None[source]¶ 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.
- timeout (float) – Timeout for required
Windows¶
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[bleak.backends.device.BLEDevice, str], **kwargs)[source]¶ Native Windows Bleak Client.
Implemented using winrt, a package that enables Python developers to access Windows Runtime APIs directly from Python.
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[source]¶ 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[source]¶ Disconnect from the specified GATT server.
Returns: Boolean representing if device is disconnected.
-
get_services
(**kwargs) → bleak.backends.service.BleakGATTServiceCollection[source]¶ Get all services registered for this GATT server.
Returns: A bleak.backends.service.BleakGATTServiceCollection
with this device’s services tree.
-
is_connected
¶ Check connection status between this client and the server.
Returns: Boolean representing connection status.
-
mtu_size
¶ Get ATT MTU size for active connection
-
pair
(protection_level: int = None, **kwargs) → bool[source]¶ Attempts to pair with the device.
Keyword Arguments: protection_level – Windows.Devices.Enumeration.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. (This will not work in Bleak…)Returns: Boolean regarding success of pairing.
-
read_gatt_char
(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], **kwargs) → bytearray[source]¶ 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 toFalse
.Returns: (bytearray) The read data.
-
read_gatt_descriptor
(handle: int, **kwargs) → bytearray[source]¶ 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.
-
start_notify
(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None[source]¶ Activate notifications/indications on a characteristic.
Callbacks must accept two inputs. The first will be a uuid string object and the second will be a bytearray.
def callback(sender, data): 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.
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.
-
stop_notify
(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID]) → None[source]¶ 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[source]¶ 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.
-
write_gatt_char
(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], data: Union[bytes, bytearray, memoryview], response: bool = False) → None[source]¶ 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.
-
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)[source]¶ 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[source]¶ 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.
-
get_services
(**kwargs) → bleak.backends.service.BleakGATTServiceCollection[source]¶ Get all services registered for this GATT server.
Returns: A bleak.backends.service.BleakGATTServiceCollection
with this device’s services tree.
-
is_connected
¶ Checks for current active connection
-
mtu_size
¶ Get ATT MTU size for active connection
-
pair
(*args, **kwargs) → bool[source]¶ 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:
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[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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.
-
write_gatt_char
(char_specifier: Union[bleak.backends.characteristic.BleakGATTCharacteristic, int, str, uuid.UUID], data: Union[bytes, bytearray, memoryview], response: bool = False) → None[source]¶ 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.
-
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)[source]¶ 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. - 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.
- adapter (str) – Bluetooth adapter to use for discovery.
-
connect
(**kwargs) → bool[source]¶ 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.
Raises: BleakError
– If the device is already connected or if the device could not be found.BleakDBusError
– If there was a D-Bus errorasyncio.TimeoutError
– If the connection timed out
-
disconnect
() → bool[source]¶ Disconnect from the specified GATT server.
Returns: Boolean representing if device is disconnected.
Raises: BleakDBusError
– If there was a D-Bus error- asyncio.TimeoutError if the device was not disconnected within 10 seconds
-
get_services
(**kwargs) → bleak.backends.service.BleakGATTServiceCollection[source]¶ Get all services registered for this GATT server.
Returns: A bleak.backends.service.BleakGATTServiceCollection
with this device’s services tree.
-
is_connected
¶ Check connection status between this client and the server.
Returns: Boolean representing connection status.
-
mtu_size
¶ Get ATT MTU size for active connection
-
pair
(*args, **kwargs) → bool[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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.
-
stop_notify
(char_specifier: Union[bleak.backends.bluezdbus.characteristic.BleakGATTCharacteristicBlueZDBus, int, str, uuid.UUID]) → None[source]¶ 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[source]¶ 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: Union[bytes, bytearray, memoryview], response: bool = False) → None[source]¶ 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.
- timeout (float) – Timeout for required
Python-for-Android/Kivy¶
BLE Client for python-for-android
-
class
bleak.backends.p4android.client.
BleakClientP4Android
(address_or_ble_device: Union[bleak.backends.device.BLEDevice, str], **kwargs)[source]¶ A python-for-android Bleak Client
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: - 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.
- adapter (str) – Bluetooth adapter to use for discovery. [unused]
-
connect
(**kwargs) → bool[source]¶ Connect to the specified GATT server.
Returns: Boolean representing connection status.
-
disconnect
() → bool[source]¶ Disconnect from the specified GATT server.
Returns: Boolean representing if device is disconnected.
-
get_services
() → bleak.backends.service.BleakGATTServiceCollection[source]¶ Get all services registered for this GATT server.
Returns: A bleak.backends.service.BleakGATTServiceCollection
with this device’s services tree.
-
is_connected
¶ Check connection status between this client and the server.
Returns: Boolean representing connection status.
-
pair
(*args, **kwargs) → bool[source]¶ 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.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID], **kwargs) → bytearray[source]¶ Perform read operation on the specified GATT characteristic.
Parameters: char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to read from, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it. Returns: (bytearray) The read data.
-
read_gatt_descriptor
(desc_specifier: Union[bleak.backends.p4android.descriptor.BleakGATTDescriptorP4Android, str, uuid.UUID], **kwargs) → bytearray[source]¶ Perform read operation on the specified GATT descriptor.
Parameters: desc_specifier (BleakGATTDescriptorP4Android, str or UUID) – The descriptor to read from, specified by either UUID or directly by the BleakGATTDescriptorP4Android object representing it. Returns: (bytearray) The read data.
-
start_notify
(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID], callback: Callable[[int, bytearray], None], **kwargs) → None[source]¶ Activate notifications/indications on a characteristic.
Callbacks must accept two inputs. The first will be an 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 (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to activate notifications/indications on a characteristic, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it.
- callback (function) – The function to be called on notification.
-
stop_notify
(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID]) → None[source]¶ Deactivate notification/indication on a specified characteristic.
Parameters: char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to deactivate notification/indication on, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android object representing it.
-
unpair
() → bool[source]¶ Unpair with the peripheral.
Returns: Boolean regarding success of unpairing.
-
write_gatt_char
(char_specifier: Union[bleak.backends.p4android.characteristic.BleakGATTCharacteristicP4Android, int, str, uuid.UUID], data: bytearray, response: bool = False) → None[source]¶ Perform a write operation on the specified GATT characteristic.
Parameters: - char_specifier (BleakGATTCharacteristicP4Android, int, str or UUID) – The characteristic to write to, specified by either integer handle, UUID or directly by the BleakGATTCharacteristicP4Android 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
(desc_specifier: Union[bleak.backends.p4android.descriptor.BleakGATTDescriptorP4Android, str, uuid.UUID], data: bytearray) → None[source]¶ Perform a write operation on the specified GATT descriptor.
Parameters: - desc_specifier (BleakGATTDescriptorP4Android, str or UUID) – The descriptor to write to, specified by either UUID or directly by the BleakGATTDescriptorP4Android object representing it.
- data (bytes or bytearray) – The data to send.
Scanning Clients¶
Interface¶
-
class
bleak.backends.scanner.
AdvertisementData
(**kwargs)[source]¶ Wrapper around the advertisement data that each platform returns upon discovery
-
class
bleak.backends.scanner.
BaseBleakScanner
(*args, **kwargs)[source]¶ Interface for Bleak Bluetooth LE Scanners
Parameters: - **detection_callback (callable or coroutine) – Optional function that will be called each time a device is discovered or advertising data has changed.
- **service_uuids (List[str]) – Optional list of service UUIDs to filter on. Only advertisements containing this advertising data will be received. Required on macOS 12 and later.
-
classmethod
discover
(timeout=5.0, **kwargs) → List[bleak.backends.device.BLEDevice][source]¶ 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:
-
discovered_devices
¶ Gets the devices registered by the BleakScanner.
Returns: A list of the devices that the scanner has discovered during the scanning.
-
classmethod
find_device_by_address
(device_identifier: str, timeout: float = 10.0, **kwargs) → Optional[bleak.backends.device.BLEDevice][source]¶ 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.
Keyword Arguments: adapter (str) – Bluetooth adapter to use for discovery.
Returns: The
BLEDevice
sought orNone
if not detected.
-
classmethod
find_device_by_filter
(filterfunc: Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], bool], timeout: float = 10.0, **kwargs) → Optional[bleak.backends.device.BLEDevice][source]¶ A convenience method for obtaining a
BLEDevice
object specified by a filter function.Parameters: - filterfunc (AdvertisementDataFilter) – A function that is called for every BLEDevice found. It should return True only for the wanted device.
- timeout (float) – Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.
Keyword Arguments: adapter (str) – Bluetooth adapter to use for discovery.
Returns: The
BLEDevice
sought orNone
if not detected.
-
get_discovered_devices
() → List[bleak.backends.device.BLEDevice][source]¶ Gets the devices registered by the BleakScanner.
Deprecated since version 0.11.0: This method will be removed in a future version of Bleak. Use the
discovered_devices
property instead.Returns: A list of the devices that the scanner has discovered during the scanning.
-
register_detection_callback
(callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]]) → None[source]¶ Register a callback that is called when a device is discovered or has a property changed.
If another callback has already been registered, it will be replaced with
callback
.None
can be used to remove the current callback.The
callback
is a function or coroutine that takes two arguments:BLEDevice
andAdvertisementData
.Parameters: callback – A function, coroutine or None
.
Windows¶
-
class
bleak.backends.winrt.scanner.
BleakScannerWinRT
(**kwargs)[source]¶ The native Windows Bleak BLE Scanner.
Implemented using Python/WinRT.
Keyword Arguments: mode (scanning) – Set to “Passive” to avoid the “Active” scanning mode. -
discovered_devices
¶ Gets the devices registered by the BleakScanner.
Returns: A list of the devices that the scanner has discovered during the scanning.
-
set_scanning_filter
(**kwargs)[source]¶ 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.
- SignalStrengthFilter (
-
macOS¶
-
class
bleak.backends.corebluetooth.scanner.
BleakScannerCoreBluetooth
(**kwargs)[source]¶ 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.
Parameters: - **timeout (double) – The scanning timeout to be used, in case of missing
stopScan_
method. - **detection_callback (callable or coroutine) – Optional function that will be called each time a device is discovered or advertising data has changed.
- **service_uuids (List[str]) – Optional list of service UUIDs to filter on. Only advertisements
containing this advertising data will be received. Required on
macOS 12 and later (unless you create an app with
py2app
).
-
discovered_devices
¶ Gets the devices registered by the BleakScanner.
Returns: A list of the devices that the scanner has discovered during the scanning.
- **timeout (double) – The scanning timeout to be used, in case of missing
Linux Distributions with BlueZ¶
-
class
bleak.backends.bluezdbus.scanner.
BleakScannerBlueZDBus
(**kwargs)[source]¶ The native Linux Bleak BLE Scanner.
For possible values for filters, see the parameters to the
SetDiscoveryFilter
method in the BlueZ docsParameters: - **detection_callback (callable or coroutine) – Optional function that will be called each time a device is discovered or advertising data has changed.
- **service_uuids (List[str]) – 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.
- **adapter (str) – Bluetooth adapter to use for discovery.
- **filters (dict) – A dict of filters to be applied on discovery.
-
discovered_devices
¶ Gets the devices registered by the BleakScanner.
Returns: A list of the devices that the scanner has discovered during the scanning.
-
set_scanning_filter
(**kwargs)[source]¶ Sets OS level scanning filters for the BleakScanner.
For possible values for filters, see the parameters to the
SetDiscoveryFilter
method in the BlueZ docsSee 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.
Python-for-Android/Kivy¶
-
class
bleak.backends.p4android.scanner.
BleakScannerP4Android
(**kwargs)[source]¶ The python-for-android Bleak BLE Scanner.
Parameters: - **detection_callback (callable or coroutine) – Optional function that will be called each time a device is discovered or advertising data has changed.
- **service_uuids (List[str]) – 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.
-
discovered_devices
¶ Gets the devices registered by the BleakScanner.
Returns: A list of the devices that the scanner has discovered during the scanning.
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, rssi=0, **kwargs)[source]¶ 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 aWindows.Devices.Enumeration.DeviceInformation
. - When using Linux backend,
details
attribute is a dict with keyspath
which has the string path to the DBus device object andprops
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 amanufacturer_data
field with a bytes-object from the advertised data.
-
name
= None¶ The advertised name of the device.
-
rssi
= None¶ RSSI, if available
- When using Windows backend, details attribute is a
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)[source]¶ Interface for the Bleak representation of a GATT Service.
-
add_characteristic
(characteristic: bleak.backends.characteristic.BleakGATTCharacteristic)[source]¶ 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][source]¶ Get a characteristic by UUID.
Parameters: uuid – The UUID to match. Returns: The first characteristic matching uuid
orNone
if no matching characteristic was found.
-
handle
¶ The handle of this service
-
uuid
¶ The UUID to this service
-
-
class
bleak.backends.service.
BleakGATTServiceCollection
[source]¶ Simple data container for storing the peripheral’s service complement.
-
add_characteristic
(characteristic: bleak.backends.characteristic.BleakGATTCharacteristic)[source]¶ 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)[source]¶ 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)[source]¶ Add a
BleakGATTService
to the service collection.Should not be used by end user, but rather by bleak itself.
-
characteristics
¶ Returns dictionary of handles mapping to BleakGATTCharacteristic
-
descriptors
¶ Returns a dictionary of integer handles mapping to BleakGATTDescriptor
-
get_characteristic
(specifier: Union[int, str, uuid.UUID]) → bleak.backends.characteristic.BleakGATTCharacteristic[source]¶ Get a characteristic by handle (int) or UUID (str or uuid.UUID)
-
get_descriptor
(handle: int) → bleak.backends.descriptor.BleakGATTDescriptor[source]¶ Get a descriptor by integer handle
-
get_service
(specifier: Union[int, str, uuid.UUID]) → bleak.backends.service.BleakGATTService[source]¶ Get a service by handle (int) or UUID (str or uuid.UUID)
-
services
¶ Returns dictionary of handles mapping 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)[source]¶ Interface for the Bleak representation of a GATT Characteristic
-
add_descriptor
(descriptor: bleak.backends.descriptor.BleakGATTDescriptor)[source]¶ 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][source]¶ Get a descriptor by handle (int) or UUID (str or uuid.UUID)
-
handle
¶ The handle for this characteristic
-
properties
¶ Properties of this characteristic
-
service_handle
¶ The integer handle of the Service containing this characteristic
-
service_uuid
¶ The UUID of the Service containing this characteristic
-
uuid
¶ The UUID for this characteristic
-
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)[source]¶ 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
-