Backend implementations
Bleak supports the following operating systems:
Windows 10, version 16299 (Fall Creators Update) and greater
Linux distributions with BlueZ >= 5.43 (See Linux backend for more details)
OS X/macOS support via Core Bluetooth API, from at least version 10.11
Partial Android support mostly using Python-for-Android/Kivy.
These pages document platform specific differences from the interface API.
Contents:
Shared Backend API
Warning
The backend APIs are not considered part of the stable API and may change without notice.
Scanner
- 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]
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.
- 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 Level of the remote device from the received advertising data or
None
if not present.New in version 0.17.
- bleak.backends.scanner.AdvertisementDataCallback
Type alias for callback called when advertisement data is received.
alias of
Callable
[[BLEDevice
,AdvertisementData
],Optional
[Coroutine
[Any
,Any
,None
]]]
- bleak.backends.scanner.AdvertisementDataFilter
Type alias for an advertisement data filter function.
Implementations should return
True
for matches, otherwiseFalse
.alias of
Callable
[[BLEDevice
,AdvertisementData
],bool
]
- class bleak.backends.scanner.BaseBleakScanner(detection_callback: Optional[Callable[[BLEDevice, AdvertisementData], Optional[Coroutine[Any, Any, None]]]], service_uuids: Optional[List[str]])[source]
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.
- call_detection_callbacks(device: BLEDevice, advertisement_data: AdvertisementData) → None[source]
Calls all registered detection callbacks.
Backend implementations should call this method when an advertisement event is received from the OS.
- create_or_update_device(address: str, name: str, details: Any, adv: AdvertisementData) → 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.
- is_allowed_uuid(service_uuids: Optional[List[str]]) → bool[source]
Check if the advertisement data contains any of the service UUIDs matching the filter. If no filter is set, this will always return
True
.- Parameters
service_uuids – The service UUIDs from the advertisement data.
- Returns
True
if the advertisement data should be allowed orFalse
if the advertisement data should be filtered out.
- register_detection_callback(callback: Optional[Callable[[BLEDevice, AdvertisementData], Optional[Coroutine[Any, Any, None]]]]) → Callable[[], None][source]
Register a callback that is called when an advertisement event from the OS is received.
The
callback
is a function or coroutine that takes two arguments:BLEDevice
andAdvertisementData
.- Parameters
callback – A function, coroutine or
None
.- Returns
A method that can be called to unregister the callback.
- 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.
- bleak.backends.scanner.get_platform_scanner_backend_type() → Type[BaseBleakScanner][source]
Gets the platform-specific
BaseBleakScanner
type.
Client
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[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.
- 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) → 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: bool
Check connection status between this client and the server.
- Returns
Boolean representing connection status.
- abstract property mtu_size: int
Gets the negotiated MTU.
- abstract async read_gatt_char(char_specifier: Union[BleakGATTCharacteristic, int, str, 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: 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[BleakGATTCharacteristic, int, str, 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(characteristic: BleakGATTCharacteristic, data: Buffer, response: bool) → None[source]
Perform a write operation on the specified GATT characteristic.
- Parameters
characteristic – The characteristic to write to.
data – The data to send.
response – If write-with-response operation should be done.
- bleak.backends.client.get_platform_client_backend_type() → Type[BaseBleakClient][source]
Gets the platform-specific
BaseBleakClient
type.