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 by name and service, and the person picks. The chooser only opens during a click or a tap (transient user activation), so call find() or nus.connect() from one. scan() raises bledev.UnsupportedError.

  • Only services you named are reachable. The browser grants the services in the find() filter and those passed as WebBLE(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.mtu is 23 (the one value every link has) unless you pass WebBLE(mtu=...) knowing the link negotiated more. The peripheral can see the real value.

bledev.webble.available()[source]

True when this page can use Web Bluetooth.

class bledev.webble.WebBLE(*, services=(), mtu=23, queue_limit=512)[source]

Bases: BLE

The browser’s Bluetooth, through navigator.bluetooth. Central only.

services lists the service UUIDs your page will use beyond those it passes to find(): the browser hides every service it wasn’t told about. mtu is the ATT MTU writes are sized to (see the module notes); leave it at 23 unless you know the link negotiated more. queue_limit bounds each notification queue.

CONNECT_ATTEMPTS = 3

How many times connect() tries before a failed connection attempt is raised. connect_retries counts the extra tries made.

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]

Stop advertising and scanning, drop connections, and turn the radio off.

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 Device picked.

The chooser lists devices matching name and/or service (all devices if neither), and service becomes reachable once connected. Given both, the chooser filters on service alone and the pick must carry name, because Chrome on Android can’t match a name that only a scan response carries. A name-only find() 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_ms doesn’t apply, because a person is choosing. Closing the chooser without choosing raises BLETimeoutError, as a scan that found nothing does.