macOS backend

The macOS backend of Bleak is written with pyobjc directives for interfacing with Foundation and CoreBluetooth APIs.

Specific features for the macOS backend

The most noticeable difference between the other backends of bleak and this backend, is that CoreBluetooth doesn’t scan for other devices via Bluetooth address. Instead, UUIDs are utilized that are often unique between the device that is scanning and the device that is being scanned.

In the example files, this is handled in this fashion:

mac_addr = (
    "24:71:89:cc:09:05"
    if platform.system() != "Darwin"
    else "243E23AE-4A99-406C-B317-18F1BD7B4CBE"
)

As stated above, this will however only work the macOS machine that performed the scan and thus cached the device as 243E23AE-4A99-406C-B317-18F1BD7B4CBE.

There is also no pairing functionality implemented in macOS right now, since it does not seem to be any explicit pairing methods in the COre Bluetooth.

API

Scanner

class bleak.backends.corebluetooth.scanner.BleakScannerCoreBluetooth(detection_callback: Optional[Callable[[BLEDevice, AdvertisementData], Optional[Coroutine[Any, Any, None]]]], service_uuids: Optional[List[str]], scanning_mode: Literal['active', 'passive'], *, cb: CBScannerArgs, **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

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.

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.

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

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. It is known to not work on macOS 10.15.

Client

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[BLEDevice, str], services: Optional[Set[str]] = None, **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.
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) → 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: bool: Checks for current active connection

property mtu_size: int: 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:

Apple Docs

Stack Overflow post #1

Stack Overflow post #2

Returns: Boolean regarding success of pairing.

async read_gatt_char(char_specifier: Union[BleakGATTCharacteristic, int, str, 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: BleakGATTCharacteristic, callback: Callable[[bytearray], None], **kwargs) → None[source]: Activate notifications/indications on a characteristic.

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.

async unpair() → bool[source]: Returns:

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.

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