bleak.backends package¶
Subpackages¶
- bleak.backends.bluezdbus package
- Submodules
- bleak.backends.bluezdbus.advertisement_monitor module
- bleak.backends.bluezdbus.characteristic module
- bleak.backends.bluezdbus.client module
- bleak.backends.bluezdbus.defs module
- bleak.backends.bluezdbus.descriptor module
- bleak.backends.bluezdbus.manager module
- bleak.backends.bluezdbus.scanner module
- bleak.backends.bluezdbus.service module
- bleak.backends.bluezdbus.signals module
- bleak.backends.bluezdbus.utils module
- bleak.backends.bluezdbus.version module
- Module contents
- bleak.backends.corebluetooth package
- Submodules
- bleak.backends.corebluetooth.CentralManagerDelegate module
- bleak.backends.corebluetooth.PeripheralDelegate module
- bleak.backends.corebluetooth.characteristic module
- bleak.backends.corebluetooth.client module
- bleak.backends.corebluetooth.descriptor module
- bleak.backends.corebluetooth.scanner module
- bleak.backends.corebluetooth.service module
- bleak.backends.corebluetooth.utils module
- Module contents
- bleak.backends.p4android package
- Submodules
- bleak.backends.p4android.characteristic module
- bleak.backends.p4android.client module
- bleak.backends.p4android.defs module
- bleak.backends.p4android.descriptor module
- bleak.backends.p4android.scanner module
- bleak.backends.p4android.service module
- bleak.backends.p4android.utils module
- Module contents
- bleak.backends.winrt package
Submodules¶
bleak.backends.characteristic module¶
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, max_write_without_response_size: int)[source]¶ Bases:
abc.ABC
Interface for the Bleak representation of a GATT Characteristic
-
abstract
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.
-
property
description
¶ Description for this characteristic
-
abstract property
descriptors
¶ List of descriptors for this service
-
abstract
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)
-
abstract property
handle
¶ The handle for this characteristic
-
property
max_write_without_response_size
¶ Gets the maximum size in bytes that can be used for the data argument of
BleakClient.write_gatt_char()
whenresponse=False
.Warning
Linux quirk: For BlueZ versions < 5.62, this property will always return
20
.New in version 0.16.0.
-
abstract property
properties
¶ Properties of this characteristic
-
abstract property
service_handle
¶ The integer handle of the Service containing this characteristic
-
abstract property
service_uuid
¶ The UUID of the Service containing this characteristic
-
abstract property
uuid
¶ The UUID for this characteristic
-
abstract
-
class
bleak.backends.characteristic.
GattCharacteristicsFlags
(value)[source]¶ Bases:
enum.Enum
An enumeration.
-
authenticated_signed_writes
= 64¶
-
broadcast
= 1¶
-
extended_properties
= 128¶
-
indicate
= 32¶
-
notify
= 16¶
-
read
= 2¶
-
reliable_write
= 256¶
-
writable_auxiliaries
= 512¶
-
write
= 8¶
-
write_without_response
= 4¶
-
bleak.backends.client module¶
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]¶ Bases:
abc.ABC
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.
-
abstract async
connect
(**kwargs) → bool[source]¶ Connect to the specified GATT server.
- Returns
Boolean representing connection status.
-
abstract async
disconnect
() → bool[source]¶ Disconnect from the specified GATT server.
- Returns
Boolean representing connection status.
-
abstract async
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.
-
abstract property
is_connected
¶ Check connection status between this client and the server.
- Returns
Boolean representing connection status.
-
abstract property
mtu_size
¶ Gets the negotiated MTU.
-
abstract async
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.
-
abstract async
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[], None]], **kwargs) → None[source]¶ Set the disconnect callback. The callback will only be called on unsolicited disconnect event.
Set the callback to
None
to remove any existing callback.- Parameters
callback – callback to be called on disconnection.
-
abstract async
start_notify
(characteristic: bleak.backends.characteristic.BleakGATTCharacteristic, callback: Callable[[bytearray], None], **kwargs) → None[source]¶ Activate notifications/indications on a characteristic.
Implementers should call the OS function to enable notifications or indications on the characteristic.
To keep things the same cross-platform, notifications should be preferred over indications if possible when a characteristic supports both.
-
abstract async
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.
-
abstract async
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.
-
bleak.backends.client.
get_platform_client_backend_type
() → Type[bleak.backends.client.BaseBleakClient][source]¶ Gets the platform-specific
BaseBleakClient
type.
bleak.backends.descriptor module¶
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]¶ Bases:
abc.ABC
Interface for the Bleak representation of a GATT Descriptor
-
abstract property
characteristic_handle
¶ handle for the characteristic that this descriptor belongs to
-
abstract property
characteristic_uuid
¶ UUID for the characteristic that this descriptor belongs to
-
property
description
¶ A text description of what this descriptor represents
-
abstract property
handle
¶ Integer handle for this descriptor
-
abstract property
uuid
¶ UUID for this descriptor
-
abstract property
bleak.backends.device module¶
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: str, name: Optional[str], details: Any, rssi: int, **kwargs)[source]¶ Bases:
object
A simple wrapper class representing a BLE server detected during scanning.
-
address
¶ The Bluetooth address of the device on this machine (UUID on macOS).
-
details
¶ The OS native details required for connecting to the device.
-
property
metadata
¶ Gets additional advertisement data for the device.
Deprecated since version 0.19.0: Use
AdvertisementData
from detection callback orBleakScanner.discovered_devices_and_advertisement_data
instead.
-
name
¶ The operating system name of the device (not necessarily the local name from the advertising data), suitable for display to the user.
-
property
rssi
¶ Gets the RSSI of the last received advertisement.
Deprecated since version 0.19.0: Use
AdvertisementData
from detection callback orBleakScanner.discovered_devices_and_advertisement_data
instead.
-
bleak.backends.scanner module¶
-
class
bleak.backends.scanner.
AdvertisementData
(local_name: Optional[str], manufacturer_data: Dict[int, bytes], service_data: Dict[str, bytes], service_uuids: List[str], tx_power: Optional[int], rssi: int, platform_data: Tuple)[source]¶ Bases:
NamedTuple
Wrapper around the advertisement data that each platform returns upon discovery
-
local_name
: Optional[str]¶ The local name of the device or
None
if not included in advertising data.
-
manufacturer_data
: Dict[int, bytes]¶ Dictionary of manufacturer data in bytes from the received advertisement data or empty dict if not present.
The keys are Bluetooth SIG assigned Company Identifiers and the values are bytes.
https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/
-
platform_data
: Tuple¶ Tuple of platform specific data.
This is not a stable API. The actual values may change between releases.
-
rssi
: int¶ The Radio Receive Signal Strength (RSSI) in dBm.
New in version 0.19.0.
-
service_data
: Dict[str, bytes]¶ Dictionary of service data from the received advertisement data or empty dict if not present.
-
service_uuids
: List[str]¶ List of service UUIDs from the received advertisement data or empty list if not present.
-
tx_power
: Optional[int]¶ Tx Power data from the received advertising data or
None
if not present.New in version 0.17.0.
-
-
bleak.backends.scanner.
AdvertisementDataCallback
¶ Type alias for callback called when advertisement data is received.
alias of Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]
-
bleak.backends.scanner.
AdvertisementDataFilter
¶ Type alias for an advertisement data filter function.
Implementations should return
True
for matches, otherwiseFalse
.alias of Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], bool]
-
class
bleak.backends.scanner.
BaseBleakScanner
(detection_callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]], service_uuids: Optional[List[str]])[source]¶ Bases:
abc.ABC
Interface for Bleak Bluetooth LE Scanners
- Parameters
detection_callback – Optional function that will be called each time a device is discovered or advertising data has changed.
service_uuids – Optional list of service UUIDs to filter on. Only advertisements containing this advertising data will be received.
-
create_or_update_device
(address: str, name: str, details: Any, adv: bleak.backends.scanner.AdvertisementData) → bleak.backends.device.BLEDevice[source]¶ Creates or updates a device in
seen_devices
.- Parameters
address – The Bluetooth address of the device (UUID on macOS).
name – The OS display name for the device.
details – The platform-specific handle for the device.
adv – The most recent advertisement data received.
- Returns
The updated device.
-
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
.
-
seen_devices
: Dict[str, Tuple[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData]]¶ Map of device identifier to BLEDevice and most recent advertisement data.
This map must be cleared when scanning starts.
-
bleak.backends.scanner.
get_platform_scanner_backend_type
() → Type[bleak.backends.scanner.BaseBleakScanner][source]¶ Gets the platform-specific
BaseBleakScanner
type.
bleak.backends.service module¶
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]¶ Bases:
abc.ABC
Interface for the Bleak representation of a GATT Service.
-
abstract
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.
-
abstract property
characteristics
¶ List of characteristics for this service
-
property
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.
-
abstract property
handle
¶ The handle of this service
-
abstract property
uuid
¶ The UUID to this service
-
abstract
-
class
bleak.backends.service.
BleakGATTServiceCollection
[source]¶ Bases:
object
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.
-
property
characteristics
¶ Returns dictionary of handles mapping to BleakGATTCharacteristic
-
property
descriptors
¶ Returns a dictionary of integer handles mapping to BleakGATTDescriptor
-
get_characteristic
(specifier: Union[int, str, uuid.UUID]) → Optional[bleak.backends.characteristic.BleakGATTCharacteristic][source]¶ Get a characteristic by handle (int) or UUID (str or uuid.UUID)
-
get_descriptor
(handle: int) → Optional[bleak.backends.descriptor.BleakGATTDescriptor][source]¶ Get a descriptor by integer handle
-
get_service
(specifier: Union[int, str, uuid.UUID]) → Optional[bleak.backends.service.BleakGATTService][source]¶ Get a service by handle (int) or UUID (str or uuid.UUID)
-
property
services
¶ Returns dictionary of handles mapping to BleakGATTService
-