bledev.webble
Web Bluetooth backend for browsers. Central only.
from bledev.webble import WebBLE ble = WebBLE() link = await nus.connect(ble, name=”rack”) # from a click handler
It runs wherever Python can reach the page’s JavaScript: PyScript on Pyodide
or MicroPython, and the direct MicroPython WebAssembly build that Workbench
uses. It needs Chrome or Edge (desktop or Android) and a secure context,
https:// or http://localhost. Firefox and iOS Safari have no Web
Bluetooth.
A browser differs from a board in three ways, and this backend says so rather than pretending:
You don’t scan; the browser’s chooser does.
find()opens the device chooser filtered bynameandservice, and the person picks. The chooser only opens during a click or a tap (transient user activation), so callfind()ornus.connect()from one.scan()raisesbledev.UnsupportedError.Only services you named are reachable. The browser grants the services in the
find()filter and those passed asWebBLE(services=[...]), and hides the rest from discovery.The browser never reports the ATT MTU. It negotiates one on its own, and a write longer than that can be cut short without an error, so
connection.mtuis 23 (the one value every link has) unless you passWebBLE(mtu=...)knowing the link negotiated more. The peripheral can see the real value.
- class bledev.webble.WebBLE(*, services=(), mtu=23, queue_limit=512)[source]
Bases:
BLEThe browser’s Bluetooth, through
navigator.bluetooth. Central only.serviceslists the service UUIDs your page will use beyond those it passes tofind(): the browser hides every service it wasn’t told about.mtuis the ATT MTU writes are sized to (see the module notes); leave it at 23 unless you know the link negotiated more.queue_limitbounds each notification queue.- CONNECT_ATTEMPTS = 3
How many times
connect()tries before a failed connection attempt is raised.connect_retriescounts the extra tries made.
- 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.
- 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 find(name=None, service=None, *, timeout_ms=10000, active=True)[source]
Open the browser’s device chooser and return the
Devicepicked.The chooser lists devices matching
nameand/orservice(all devices if neither), andservicebecomes reachable once connected. Given both, the chooser filters onservicealone and the pick must carryname, because Chrome on Android can’t match a name that only a scan response carries. A name-onlyfind()works there only if the board’s name fits in its advertisement. Call it from a click or a tap: the browser refuses otherwise.timeout_msdoesn’t apply, because a person is choosing. Closing the chooser without choosing raisesBLETimeoutError, as a scan that found nothing does.