bleak.backends package

Subpackages

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

Interface for the Bleak representation of a GATT Characteristic

abstract add_descriptor(descriptor: BleakGATTDescriptor)[source]

Add a BleakGATTDescriptor to the characteristic.

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

property description: str: Description for this characteristic

abstract property descriptors: List[BleakGATTDescriptor]: List of descriptors for this service

abstract get_descriptor(specifier: Union[int, str, UUID]) → Optional[BleakGATTDescriptor][source]: Get a descriptor by handle (int) or UUID (str or uuid.UUID)

abstract property handle: int: The handle for this characteristic

property max_write_without_response_size: int: Gets the maximum size in bytes that can be used for the data argument of BleakClient.write_gatt_char() when response=False.

Warning

Linux quirk: For BlueZ versions < 5.62, this property will always return 20.

New in version 0.16.0.

abstract property properties: List[str]: Properties of this characteristic

abstract property service_handle: int: The integer handle of the Service containing this characteristic

abstract property service_uuid: str: The UUID of the Service containing this characteristic

abstract property uuid: str: The UUID for this characteristic

class bleak.backends.characteristic.GattCharacteristicsFlags(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

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[BLEDevice, str], **kwargs)[source]

Bases: 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) → 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 pair(*args, **kwargs) → bool[source]: Pair with the peripheral.

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 unpair() → bool[source]: Unpair with the peripheral.

abstract async write_gatt_char(characteristic: BleakGATTCharacteristic, data: typing_extensions.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.

abstract async write_gatt_descriptor(handle: int, data: typing_extensions.Buffer) → None[source]

Perform a write operation on the specified GATT descriptor.

Parameters:

handle – The handle of the descriptor to read from.
data – The data to send (any bytes-like object).

bleak.backends.client.get_platform_client_backend_type() → Type[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

Interface for the Bleak representation of a GATT Descriptor

abstract property characteristic_handle: int: handle for the characteristic that this descriptor belongs to

abstract property characteristic_uuid: str: UUID for the characteristic that this descriptor belongs to

property description: str: A text description of what this descriptor represents

abstract property handle: int: Integer handle for this descriptor

abstract property uuid: str: UUID for this descriptor

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: dict: Gets additional advertisement data for the device.

Deprecated since version 0.19.0: Use AdvertisementData from detection callback or BleakScanner.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: int: Gets the RSSI of the last received advertisement.

Deprecated since version 0.19.0: Use AdvertisementData from detection callback or BleakScanner.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[[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, otherwise False.

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]

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

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.

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

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.

abstract set_scanning_filter(**kwargs) → None[source]

Set scanning filter for the BleakScanner.

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

abstract async start() → None[source]: Start scanning for devices

abstract async stop() → None[source]: Stop scanning for devices

bleak.backends.scanner.get_platform_scanner_backend_type() → Type[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

Interface for the Bleak representation of a GATT Service.

abstract add_characteristic(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[BleakGATTCharacteristic]: List of characteristics for this service

property description: str: String description for this service

get_characteristic(uuid: Union[str, UUID]) → Optional[BleakGATTCharacteristic][source]

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.

abstract property handle: int: The handle of this service

abstract property uuid: str: The UUID to this service

class bleak.backends.service.BleakGATTServiceCollection[source]

Bases: object

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

add_characteristic(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: BleakGATTDescriptor)[source]

Add a BleakGATTDescriptor to the service collection.

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

add_service(service: BleakGATTService)[source]

Add a BleakGATTService to the service collection.

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

property characteristics: Dict[int, BleakGATTCharacteristic]: Returns dictionary of handles mapping to BleakGATTCharacteristic

property descriptors: Dict[int, BleakGATTDescriptor]: Returns a dictionary of integer handles mapping to BleakGATTDescriptor

get_characteristic(specifier: Union[int, str, UUID]) → Optional[BleakGATTCharacteristic][source]: Get a characteristic by handle (int) or UUID (str or uuid.UUID)

get_descriptor(handle: int) → Optional[BleakGATTDescriptor][source]: Get a descriptor by integer handle

get_service(specifier: Union[int, str, UUID]) → Optional[BleakGATTService][source]: Get a service by handle (int) or UUID (str or uuid.UUID)

property services: Dict[int, BleakGATTService]: Returns dictionary of handles mapping to BleakGATTService

Module contents

__init__.py

Created on 2017-11-19 by hbldh <henrik.blidh@nedomkull.com>