Pythonista iOS app backend

Pythonista iOS app backend of Bleak is written as 3rd-party module bleak-pythonista with pythonista built-in _cb module (CoreBluetooth wrapper) directives for interfacing

This backend refers to Pythonista.cb docs
This backend refers to existing macOS CoreBluetooth bleak backend was used as a reference
It also provides stub files for pythonista built-in modules as _cb and pythonista.cb, and fake _cb.py implementation for testing on unsupported platforms
Use Bleak docs to explore how to use Bleak

Note

bleak-pythonista sources aren’t included with Bleak. Explore them here: bleak-pythonista on GitHub

Optional installation with Bleak

Use StaSh or Pythonista3_pip_Configration_Tool for pip

$ pip install bleak[pythonista]

Specific features for the Pythonista iOS app backend

The most noticeable difference between the other backends of bleak and this backend, is that pythonista _cb (CoreBluetooth wrapper) 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 sys.platform != "darwin"
    else "243E23AE-4A99-406C-B317-18F1BD7B4CBE"
)

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

Pairing

There is no pairing functionality implemented in Pythonista iOS app right now, since it does not seem to be any explicit pairing methods in Pythonista _cb (CoreBluetooth wrapper).

Instead, iOS will prompt the user the first time a characteristic that requires authorization/authentication is accessed. This means that a GATT read or write operation could block for a long time waiting for the user to response. So timeouts should be set accordingly.

Calling the bleak.BleakClient.pair() method will raise a NotImplementedError on iOS. But setting pair=True in bleak.BleakClient will be silently ignored.

Characteristic descriptors

There is no functionality to get characteristic descriptors implemented in Pythonista iOS app right now.

Calling the bleak.BleakClient.read_gatt_descriptor() method will raise a NotImplementedError on Pythonista iOS app. Calling the bleak.BleakClient.write_gatt_descriptor() method will raise a NotImplementedError on Pythonista iOS app.

Notifications

Pythonista _cb (CoreBluetooth wrapper) does not differentiate between data from a notification and data from a read. This can cause confusion in cases where a device may send a notification message on a characteristic as a signal that the characteristic needs to be read again.

Bleak can accept a notification_discriminator callback in the cb dict parameter that is passed to the bleak.BleakClient.start_notify() method that can differentiate between these types of data.

event = asyncio.Event()

async def notification_handler(char, data):
    event.set()

def notification_check_handler(data):
    # We can identify notifications on this characteristic because they
    # only contain 1 byte of data. Read responses will have more than
    # 1 byte.
    return len(data) == 1

await client.start_notify(
    char,
    notification_handler,
    cb={"notification_discriminator": notification_check_handler},
)

while True:
    await event.wait()
    # We received a notification - prepare to receive another
    event.clear()
    # Then read the characteristic to get the full value
    data = await client.read_gatt_char(char)
    # Do stuff with data