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
-
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]¶
-
init
() → Optional[bleak.backends.corebluetooth.CentralManagerDelegate.CentralManagerDelegate][source]¶ macOS init function for NSObject
-
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_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_descriptors
(characteristic: CoreBluetooth.CBCharacteristic) → 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
-
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
start_notifications
(characteristic: CoreBluetooth.CBCharacteristic, callback: Callable[[bytearray], None]) → 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
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
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.
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
-
property
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 raiseBleakError
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.
-
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
)