bledev.bleak

CPython backend over bleak: Windows, Linux and macOS. Central only.

from bledev.bleak import BleakBLE ble = BleakBLE()

Needs bleak (pip install "omnipython[ble]"). A laptop can scan and connect but can’t advertise, so advertise() and register_services() raise bledev.UnsupportedError; capabilities() says so up front.

Where bleak and the operating system differ from the contract, this backend translates:

  • bleak hands every notification to a callback. Here each subscribed characteristic gets a queue of queue_limit entries, and an overflow raises from the next notified() rather than dropping data.

  • The OS negotiates the MTU on its own. exchange_mtu() waits briefly for that negotiation to finish and returns the result; it can’t ask for a particular value. BlueZ always reports 23 through bleak, so on Linux the MTU comes from the characteristics’ write-without-response size instead.

  • A write longer than mtu - 3 raises bledev.BLEError before it reaches the OS, as on every backend, even though a write with response could go out as a long write.

  • bleak can’t tell a notification from an indication. Data goes to indicated() when you subscribed with indicate=True alone, and to notified() otherwise.

  • On Windows, connect(pair=True, passkey=...) pairs before it connects, on a link Windows opens for the pairing. A bledev board asks a host to pair the moment it connects, and once a link is up Windows answers that on its own, out of sight, so a later pair() fails without asking for the passkey. bledev.connect_and_set_up (and so nus, repl and filetransfer with pair=True) pairs this way.

  • On Windows, connect(priority="throughput") (or asking for a connection interval of 15 ms or less, as nus.connect() does on a board) asks WinRT for its throughput-optimized parameters, which roughly quarters the time a GATT round trip takes. Other hosts ignore it.

class bledev.bleak.BleakBLE(*, queue_limit=1024, mtu=517, scanner_args=None, client_args=None)[source]

Bases: BLE

The host’s Bluetooth adapter, through bleak. Central only.

queue_limit bounds each notification queue. mtu is recorded for config("mtu"); the OS picks the real value. Extra keyword arguments in scanner_args and client_args go to BleakScanner and BleakClient (for example {"bluez": {"adapter": "hci1"}}).

pairs_on_connect = True

connect() takes pair and passkey, and pairs before the link is up where the OS needs that (Windows).

capabilities()[source]

A dict describing this backend. Keys every backend provides:

backend (its module name), central and peripheral (which roles it can take), mtu (the ATT MTU it asks for), max_mtu, indicate, pairing and l2cap (bools), long_read: whether a read returns values longer than one packet (mtu - 1), and write_notifies: whether setting a served characteristic’s value already notifies its subscribers (CircuitPython’s _bleio).

config(*names, **settings)[source]

Read or set adapter settings, like bluetooth.BLE.config.

config(mtu=247) sets the ATT MTU this side asks for; config("mtu") reads it. gap_name is the device name in the GAP service. addr_mode is the address the radio uses on the air: ADDR_MODE_PUBLIC, ADDR_MODE_RANDOM, ADDR_MODE_RPA (a resolvable private address that rotates, so a phone can’t follow the board except through a bond) or ADDR_MODE_NRPA. Set it before you advertise or scan. A setting the backend doesn’t have raises UnsupportedError.

close()[source]

Drop every connection. The OS disconnects in the background; aclose() waits for it.

async aclose()[source]

close(), waiting until the OS has let go of every connection.

scan(duration_ms, *, active=False, interval_us=None, window_us=None)[source]

Scan for duration_ms. Use as:

async with ble.scan(5000, active=True) as scanner:
    async for result in scanner:
        ...

A device can be yielded more than once as its data arrives. An active scan also asks for scan responses, which is where a long name ends up.

async bledev.bleak.unpair(address)[source]

Remove the OS’s pairing with address without connecting: the recovery step when a board has lost its bond (its keys were erased) and Windows still holds the other half.