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_limitentries, and an overflow raises from the nextnotified()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 - 3raisesbledev.BLEErrorbefore 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 withindicate=Truealone, and tonotified()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 laterpair()fails without asking for the passkey.bledev.connect_and_set_up(and sonus,replandfiletransferwithpair=True) pairs this way.On Windows,
connect(priority="throughput")(or asking for a connection interval of 15 ms or less, asnus.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:
BLEThe host’s Bluetooth adapter, through bleak. Central only.
queue_limitbounds each notification queue.mtuis recorded forconfig("mtu"); the OS picks the real value. Extra keyword arguments inscanner_argsandclient_argsgo toBleakScannerandBleakClient(for example{"bluez": {"adapter": "hci1"}}).- pairs_on_connect = True
connect()takespairandpasskey, 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),centralandperipheral(which roles it can take),mtu(the ATT MTU it asks for),max_mtu,indicate,pairingandl2cap(bools),long_read: whether a read returns values longer than one packet (mtu - 1), andwrite_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_nameis the device name in the GAP service.addr_modeis 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) orADDR_MODE_NRPA. Set it before you advertise or scan. A setting the backend doesn’t have raisesUnsupportedError.
- close()[source]
Drop every connection. The OS disconnects in the background;
aclose()waits for it.
- 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.