bleak.backends.corebluetooth package

Submodules

bleak.backends.corebluetooth.CentralManagerDelegate module

CentralManagerDelegate will implement the CBCentralManagerDelegate protocol to manage CoreBluetooth services and resources on the Central End

Created on June, 25 2019 by kevincar <kevincarrolldavis@gmail.com>

class bleak.backends.corebluetooth.CentralManagerDelegate.CentralManagerDelegate(*args: Any, **kwargs: Any)[source]

Bases: Foundation.

macOS conforming python class for managing the CentralManger for BLE

centralManagerDidUpdateState_(centralManager: CoreBluetooth.CBCentralManager) → None[source]
centralManager_didConnectPeripheral_(central: CoreBluetooth.CBCentralManager, peripheral: CoreBluetooth.CBPeripheral) → None[source]
centralManager_didDisconnectPeripheral_error_(central: CoreBluetooth.CBCentralManager, peripheral: CoreBluetooth.CBPeripheral, error: Optional[Foundation.NSError]) → None[source]
centralManager_didDiscoverPeripheral_advertisementData_RSSI_(central: CoreBluetooth.CBCentralManager, peripheral: CoreBluetooth.CBPeripheral, advertisementData: Foundation.NSDictionary, RSSI: Foundation.NSNumber) → None[source]
centralManager_didFailToConnectPeripheral_error_(centralManager: CoreBluetooth.CBCentralManager, peripheral: CoreBluetooth.CBPeripheral, error: Optional[Foundation.NSError]) → None[source]
async connect(peripheral: CoreBluetooth.CBPeripheral, disconnect_callback: Callable[], None], timeout=10.0) → None[source]
did_connect_peripheral(central: CoreBluetooth.CBCentralManager, peripheral: CoreBluetooth.CBPeripheral) → None[source]
did_disconnect_peripheral(central: CoreBluetooth.CBCentralManager, peripheral: CoreBluetooth.CBPeripheral, error: Optional[Foundation.NSError]) → None[source]
did_discover_peripheral(central: CoreBluetooth.CBCentralManager, peripheral: CoreBluetooth.CBPeripheral, advertisementData: Foundation.NSDictionary, RSSI: Foundation.NSNumber) → None[source]
did_fail_to_connect_peripheral(centralManager: CoreBluetooth.CBCentralManager, peripheral: CoreBluetooth.CBPeripheral, error: Optional[Foundation.NSError]) → None[source]
async disconnect(peripheral: CoreBluetooth.CBPeripheral) → None[source]
init() → Optional[bleak.backends.corebluetooth.CentralManagerDelegate.CentralManagerDelegate][source]

macOS init function for NSObject

observeValueForKeyPath_ofObject_change_context_(keyPath: Foundation.NSString, object: Any, change: Foundation.NSDictionary, context: int) → None[source]
async start_scan(service_uuids) → None[source]
async stop_scan() → None[source]

bleak.backends.corebluetooth.PeripheralDelegate module

PeripheralDelegate

Created by kevincar <kevincarrolldavis@gmail.com>

class bleak.backends.corebluetooth.PeripheralDelegate.PeripheralDelegate(*args: Any, **kwargs: Any)[source]

Bases: Foundation.

macOS conforming python class for managing the PeripheralDelegate for BLE

did_discover_characteristics_for_service(peripheral: CoreBluetooth.CBPeripheral, service: CoreBluetooth.CBService, characteristics: Foundation.NSArray, error: Optional[Foundation.NSError])[source]
did_discover_descriptors_for_characteristic(peripheral: CoreBluetooth.CBPeripheral, characteristic: CoreBluetooth.CBCharacteristic, error: Optional[Foundation.NSError])[source]
did_discover_services(peripheral: CoreBluetooth.CBPeripheral, services: Foundation.NSArray, error: Optional[Foundation.NSError]) → None[source]
did_modify_services(peripheral: CoreBluetooth.CBPeripheral, invalidated_services: Foundation.NSArray) → None[source]
did_read_rssi(peripheral: CoreBluetooth.CBPeripheral, rssi: Foundation.NSNumber, error: Optional[Foundation.NSError]) → None[source]
did_update_name(peripheral: CoreBluetooth.CBPeripheral, name: Foundation.NSString) → None[source]
did_update_notification_for_characteristic(peripheral: CoreBluetooth.CBPeripheral, characteristic: CoreBluetooth.CBCharacteristic, error: Optional[Foundation.NSError])[source]
did_update_value_for_characteristic(peripheral: CoreBluetooth.CBPeripheral, characteristic: CoreBluetooth.CBCharacteristic, value: Foundation.NSData, error: Optional[Foundation.NSError])[source]
did_update_value_for_descriptor(peripheral: CoreBluetooth.CBPeripheral, descriptor: CoreBluetooth.CBDescriptor, value: Foundation.NSObject, error: Optional[Foundation.NSError])[source]
did_write_value_for_characteristic(peripheral: CoreBluetooth.CBPeripheral, characteristic: CoreBluetooth.CBCharacteristic, error: Optional[Foundation.NSError])[source]
did_write_value_for_descriptor(peripheral: CoreBluetooth.CBPeripheral, descriptor: CoreBluetooth.CBDescriptor, error: Optional[Foundation.NSError])[source]
async discover_characteristics(service: CoreBluetooth.CBService) → Foundation.NSArray[source]
async discover_descriptors(characteristic: CoreBluetooth.CBCharacteristic) → Foundation.NSArray[source]
async discover_services(services: Optional[Foundation.NSArray]) → Foundation.NSArray[source]
futures() → Iterable[_asyncio.Future][source]

Gets all futures for this delegate.

These can be used to handle any pending futures when a peripheral is disconnected.

initWithPeripheral_(peripheral: CoreBluetooth.CBPeripheral)[source]

macOS init function for NSObject

peripheralDidUpdateName_(peripheral: CoreBluetooth.CBPeripheral) → None[source]
peripheral_didDiscoverCharacteristicsForService_error_(peripheral: CoreBluetooth.CBPeripheral, service: CoreBluetooth.CBService, error: Optional[Foundation.NSError])[source]
peripheral_didDiscoverDescriptorsForCharacteristic_error_(peripheral: CoreBluetooth.CBPeripheral, characteristic: CoreBluetooth.CBCharacteristic, error: Optional[Foundation.NSError])[source]
peripheral_didDiscoverServices_(peripheral: CoreBluetooth.CBPeripheral, error: Optional[Foundation.NSError]) → None[source]
peripheral_didModifyServices_(peripheral: CoreBluetooth.CBPeripheral, invalidatedServices: Foundation.NSArray) → None[source]
peripheral_didUpdateNotificationStateForCharacteristic_error_(peripheral: CoreBluetooth.CBPeripheral, characteristic: CoreBluetooth.CBCharacteristic, error: Optional[Foundation.NSError])[source]
peripheral_didUpdateValueForCharacteristic_error_(peripheral: CoreBluetooth.CBPeripheral, characteristic: CoreBluetooth.CBCharacteristic, error: Optional[Foundation.NSError])[source]
peripheral_didUpdateValueForDescriptor_error_(peripheral: CoreBluetooth.CBPeripheral, descriptor: CoreBluetooth.CBDescriptor, error: Optional[Foundation.NSError])[source]
peripheral_didWriteValueForCharacteristic_error_(peripheral: CoreBluetooth.CBPeripheral, characteristic: CoreBluetooth.CBCharacteristic, error: Optional[Foundation.NSError])[source]
peripheral_didWriteValueForDescriptor_error_(peripheral: CoreBluetooth.CBPeripheral, descriptor: CoreBluetooth.CBDescriptor, error: Optional[Foundation.NSError])[source]
async read_characteristic(characteristic: CoreBluetooth.CBCharacteristic, use_cached: bool = True, timeout: int = 20) → Foundation.NSData[source]
async read_descriptor(descriptor: CoreBluetooth.CBDescriptor, use_cached: bool = True) → Any[source]
async read_rssi() → Foundation.NSNumber[source]
async start_notifications(characteristic: CoreBluetooth.CBCharacteristic, callback: Callable[[bytearray], None]) → None[source]
async stop_notifications(characteristic: CoreBluetooth.CBCharacteristic) → None[source]
async write_characteristic(characteristic: CoreBluetooth.CBCharacteristic, value: Foundation.NSData, response: CBCharacteristicWriteType) → None[source]
async write_descriptor(descriptor: CoreBluetooth.CBDescriptor, value: Foundation.NSData) → None[source]
bleak.backends.corebluetooth.PeripheralDelegate.peripheralDidUpdateRSSI_error_(self: bleak.backends.corebluetooth.PeripheralDelegate.PeripheralDelegate, peripheral: CoreBluetooth.CBPeripheral, error: Optional[Foundation.NSError]) → None[source]

bleak.backends.corebluetooth.characteristic module

Interface class for the Bleak representation of a GATT Characteristic

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

class bleak.backends.corebluetooth.characteristic.BleakGATTCharacteristicCoreBluetooth(obj: CoreBluetooth.CBCharacteristic, max_write_without_response_size: int)[source]

Bases: bleak.backends.characteristic.BleakGATTCharacteristic

GATT Characteristic implementation for the CoreBluetooth backend

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 descriptors

List of descriptors for this service

get_descriptor(specifier) → Optional[bleak.backends.descriptor.BleakGATTDescriptor][source]

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

property handle

Integer handle for this characteristic

property properties

Properties of this characteristic

property service_handle

The integer handle of the Service containing this characteristic

property service_uuid

The uuid of the Service containing this characteristic

property uuid

The uuid of this characteristic

class bleak.backends.corebluetooth.characteristic.CBCharacteristicProperties(value)[source]

Bases: enum.Enum

An enumeration.

AUTHENTICATED_SIGNED_WRITES = 64
BROADCAST = 1
EXTENDED_PROPERTIES = 128
INDICATE = 32
INDICATE_ENCRYPTION_REQUIRED = 512
NOTIFY = 16
NOTIFY_ENCRYPTION_REQUIRED = 256
READ = 2
WRITE = 8
WRITE_WITHOUT_RESPONSE = 4

bleak.backends.corebluetooth.client module

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], services: Optional[Set[str]] = None, **kwargs)[source]

Bases: bleak.backends.client.BaseBleakClient

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.

  • services – Optional set of service UUIDs that will be used.

Keyword Arguments

timeout (float) – Timeout for required BleakScanner.find_device_by_address call. Defaults to 10.0.

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

async disconnect() → bool[source]

Disconnect from the peripheral device

async get_rssi() → int[source]

To get RSSI value in dBm of the connected Peripheral

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.

property is_connected

Checks for current active connection

property mtu_size

Get ATT MTU size for active connection

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

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

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

async start_notify(characteristic: bleak.backends.characteristic.BleakGATTCharacteristic, callback: Callable[[bytearray], None], **kwargs) → None[source]

Activate notifications/indications on a characteristic.

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.

async unpair() → bool[source]

Returns:

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

async write_gatt_descriptor(handle: int, data: Union[bytes, bytearray, memoryview]) → None[source]

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.

bleak.backends.corebluetooth.descriptor module

Interface class for the Bleak representation of a GATT Descriptor

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

class bleak.backends.corebluetooth.descriptor.BleakGATTDescriptorCoreBluetooth(obj: CoreBluetooth.CBDescriptor, characteristic_uuid: str, characteristic_handle: int)[source]

Bases: bleak.backends.descriptor.BleakGATTDescriptor

GATT Descriptor implementation for CoreBluetooth backend

property characteristic_handle

handle for the characteristic that this descriptor belongs to

property characteristic_uuid

UUID for the characteristic that this descriptor belongs to

property handle

Integer handle for this descriptor

property uuid

UUID for this descriptor

bleak.backends.corebluetooth.scanner module

class bleak.backends.corebluetooth.scanner.BleakScannerCoreBluetooth(detection_callback: Optional[Callable[[bleak.backends.device.BLEDevice, bleak.backends.scanner.AdvertisementData], Optional[Awaitable[None]]]], service_uuids: Optional[List[str]], scanning_mode: Literal[active, passive], *, cb: bleak.backends.corebluetooth.scanner.CBScannerArgs, **kwargs)[source]

Bases: bleak.backends.scanner.BaseBleakScanner

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
  • 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. Required on macOS >= 12.0, < 12.3 (unless you create an app with py2app).

  • scanning_mode – Set to "passive" to avoid the "active" scanning mode. Not supported on macOS! Will raise BleakError if set to "passive"

  • **timeout (float) – The scanning timeout to be used, in case of missing stopScan_ method.

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

set_scanning_filter(**kwargs) → None[source]

Set scanning filter for the scanner.

Note

This is not implemented for macOS yet.

Raises

NotImplementedError

async start() → None[source]

Start scanning for devices

async stop() → None[source]

Stop scanning for devices

class bleak.backends.corebluetooth.scanner.CBScannerArgs[source]

Bases: TypedDict

Platform-specific BleakScanner args for the CoreBluetooth backend.

use_bdaddr: bool

If true, use Bluetooth address instead of UUID.

Warning

This uses an undocumented IOBluetooth API to get the Bluetooth address and may break in the future macOS releases.

bleak.backends.corebluetooth.service module

class bleak.backends.corebluetooth.service.BleakGATTServiceCoreBluetooth(obj: CoreBluetooth.CBService)[source]

Bases: bleak.backends.service.BleakGATTService

GATT Characteristic implementation for the CoreBluetooth backend

add_characteristic(characteristic: bleak.backends.corebluetooth.characteristic.BleakGATTCharacteristicCoreBluetooth)[source]

Add a BleakGATTCharacteristicCoreBluetooth to the service.

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

property characteristics

List of characteristics for this service

property handle

The integer handle of this service

property uuid

UUID for this service.

bleak.backends.corebluetooth.utils module

bleak.backends.corebluetooth.utils.cb_uuid_to_str(uuid: CoreBluetooth.CBUUID) → str[source]

Converts a CoreBluetooth UUID to a Python string.

If uuid is a 16-bit UUID, it is assumed to be a Bluetooth GATT UUID (0000xxxx-0000-1000-8000-00805f9b34fb).

Args

uuid: The UUID.

Returns

The UUID as a lower case Python string (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx)

Module contents

__init__.py

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