# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""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.
"""
import asyncio
import json
from . import (
BLE,
BLEError,
BLETimeoutError,
ClientCharacteristic,
ClientService,
Connection,
DEFAULT_MTU,
Device,
DisconnectedError,
FLAG_INDICATE,
FLAG_NOTIFY,
FLAG_READ,
FLAG_WRITE,
FLAG_WRITE_NO_RESPONSE,
GattError,
MAX_MTU,
UnsupportedError,
UUID,
wait_ms,
)
try:
import js
except ImportError: # not in a browser; importing still works for tooling
js = None
def _find_create_proxy():
for name in ("pyodide.ffi", "jsffi", "pyscript.ffi"):
try:
module = __import__(name, None, None, ["create_proxy"])
return module.create_proxy
except (ImportError, AttributeError):
pass
return None
create_proxy = _find_create_proxy() if js is not None else None
# Everything that crosses into JavaScript goes through these few helpers, so
# Pyodide and MicroPython see the same thing: strings, numbers, booleans and
# opaque objects. Bytes cross as hex, which both runtimes convert the same way
# and which costs nothing next to a radio.
_HELPERS_JS = """
const hex = (v) => {
let s = "";
for (let i = 0; i < v.byteLength; i++) {
const b = v.getUint8(i);
s += (b < 16 ? "0" : "") + b.toString(16);
}
return s;
};
return {
available: () => !!(globalThis.navigator && navigator.bluetooth),
toBytes: (h) => {
const a = new Uint8Array(h.length >> 1);
for (let i = 0; i < a.length; i++) a[i] = parseInt(h.substr(i * 2, 2), 16);
return a;
},
hex: hex,
props: (c) => {
const p = c.properties;
return (p.read ? 0x02 : 0) | (p.writeWithoutResponse ? 0x04 : 0) | (p.write ? 0x08 : 0)
| (p.notify ? 0x10 : 0) | (p.indicate ? 0x20 : 0);
},
listen: (target, type, cb) => {
const f = (e) => cb(type === "characteristicvaluechanged" ? hex(e.target.value) : "");
target.addEventListener(type, f);
return f;
},
unlisten: (target, type, f) => target.removeEventListener(type, f),
errorName: (e) => (e && e.name) ? String(e.name) : "",
errorMessage: (e) => (e && e.message) ? String(e.message) : String(e),
isNull: (v) => v === null || v === undefined,
length: (a) => a.length,
item: (a, i) => a[i],
};
"""
_helpers = None
def _h():
global _helpers
if _helpers is None:
if js is None:
raise UnsupportedError("bledev.webble needs a browser: PyScript, Pyodide or MicroPython WebAssembly")
_helpers = js.Function.new(_HELPERS_JS)()
return _helpers
[docs]
def available():
"""True when this page can use Web Bluetooth."""
if js is None:
return False
try:
return bool(_h().available())
except Exception:
return False
def _to_js_bytes(data):
return _h().toBytes(bytes(data).hex())
def _from_hex(text):
return bytes.fromhex(str(text))
def _items(array):
h = _h()
return [h.item(array, i) for i in range(int(h.length(array)))]
def _proxy(fn):
return create_proxy(fn) if create_proxy is not None else fn
# ---------------------------------------------------------------- errors
def _error_parts(e):
"""(name, message) of a JavaScript error, from either runtime's exception."""
name = ""
message = ""
for holder in (e, getattr(e, "js_error", None)):
if holder is None:
continue
try:
n = getattr(holder, "name", None)
if n and isinstance(n, str) and not name:
name = n
m = getattr(holder, "message", None)
if m and isinstance(m, str) and not message:
message = m
except Exception:
pass
if not name and getattr(e, "args", None):
# MicroPython: JsException(error, name, message)
args = e.args
if len(args) >= 2 and isinstance(args[1], str):
name = args[1]
if len(args) >= 3 and isinstance(args[2], str):
message = args[2]
text = str(e)
if not name:
head = text.split(":", 1)[0].strip()
if head.endswith("Error") and " " not in head:
name = head
return name, message or text
def _is_js_error(e):
return type(e).__name__ in ("JsException", "JsError") or hasattr(e, "js_error")
def _translate(e, what, connection=None):
"""A bledev error for the JavaScript error ``e``, or ``None`` to re-raise it."""
if isinstance(e, BLEError):
return e
if not _is_js_error(e):
return None
name, message = _error_parts(e)
detail = "{}: {} ({})".format(what, message, name or "Error")
if connection is not None and not connection.is_connected():
return DisconnectedError(detail)
if name == "NetworkError":
# Chrome's word for a dropped link, and for a GATT request that failed
# on the air. The disconnect event may lag the rejection by a moment.
if "disconnect" in message.lower():
return DisconnectedError(detail)
return GattError(0, detail)
if name == "NotSupportedError":
return UnsupportedError(detail)
if name == "NotAllowedError" and "gatt" in message.lower():
return GattError(0, detail)
return BLEError(detail)
async def _settle(promise):
# MicroPython's asyncio only wraps coroutines in tasks, and a JS promise
# isn't one, so wait_for() needs this around it.
return await promise
async def _await(promise, what, connection=None, timeout_ms=None):
try:
if timeout_ms is None:
return await promise
return await wait_ms(_settle(promise), timeout_ms, what)
except BLETimeoutError:
raise
except Exception as e:
err = _translate(e, what, connection)
if err is None:
raise
raise err
# ---------------------------------------------------------------- the adapter
[docs]
class WebBLE(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.
"""
backend = "webble"
#: How many times ``connect()`` tries before a failed connection attempt
#: is raised. ``connect_retries`` counts the extra tries made.
CONNECT_ATTEMPTS = 3
def __init__(self, *, services=(), mtu=DEFAULT_MTU, queue_limit=512):
if not available():
raise UnsupportedError(
"this browser has no Web Bluetooth: use Chrome or Edge on desktop or "
"Android, from https:// or http://localhost"
)
self.bluetooth = js.navigator.bluetooth
self.optional_services = [UUID(s) for s in services]
self.link_mtu = int(mtu)
self.queue_limit = queue_limit
self._requested_mtu = DEFAULT_MTU
self._gap_name = None
self._connections = []
self.connect_retries = 0
[docs]
def capabilities(self):
caps = BLE.capabilities(self)
caps.update(
central=True,
peripheral=False,
mtu=self.link_mtu,
max_mtu=MAX_MTU,
indicate=True,
)
return caps
[docs]
def config(self, *names, **settings):
# The browser negotiates the MTU on its own and never says what it
# got, so an MTU set here is recorded, not used; see WebBLE(mtu=...).
for key, value in settings.items():
if key == "mtu":
self._requested_mtu = int(value)
else:
raise UnsupportedError("webble has no setting {!r}".format(key))
if names:
if len(names) != 1:
raise ValueError("read one setting at a time")
if names[0] == "mtu":
return self._requested_mtu
raise UnsupportedError("webble has no setting {!r}".format(names[0]))
return None
[docs]
def close(self):
for connection in list(self._connections):
connection._drop()
self._connections = []
# -- central
[docs]
def scan(self, duration_ms, *, active=False, interval_us=None, window_us=None):
raise UnsupportedError(
"browsers don't scan for pages; find() opens the browser's device chooser instead"
)
def _request_options(self, name, service):
filters = []
if name is not None or service is not None:
f = {}
# Chrome on Android matches a name filter only against the
# advertisement itself, never the scan response, and a board that
# advertises a 128-bit service (nus does) has its name pushed into
# the scan response. So with a service to filter on, filter on that
# alone; the chooser still shows names, and find() checks the pick.
if name is not None and service is None:
f["name"] = name
if service is not None:
f["services"] = [str(UUID(service))]
filters.append(f)
optional = [str(u) for u in self.optional_services]
if service is not None and str(UUID(service)) not in optional:
optional.append(str(UUID(service)))
options = {"optionalServices": optional}
if filters:
options["filters"] = filters
else:
options["acceptAllDevices"] = True
return js.JSON.parse(json.dumps(options))
[docs]
async def find(self, name=None, service=None, *, timeout_ms=10000, active=True):
"""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.
"""
options = self._request_options(name, service)
try:
native = await self.bluetooth.requestDevice(options)
except Exception as e:
ename, message = _error_parts(e)
if ename == "NotFoundError":
raise BLETimeoutError("no device chosen: {}".format(message))
if ename == "SecurityError":
raise BLEError(
"the browser refused to open its device chooser ({}). Call find() "
"from a click or tap handler, on https:// or localhost".format(message)
)
err = _translate(e, "requestDevice")
if err is None:
raise
raise err
dev_name = native.name
dev_name = None if _h().isNull(dev_name) else str(dev_name)
if name is not None and service is not None and dev_name != name:
raise BLEError("the chooser returned {!r}, not {!r}".format(dev_name, name))
return Device(self, str(native.id), name=dev_name, native=native)
async def _connect(self, device, timeout_ms, **options):
native = device.native
if native is None:
raise BLEError("a browser can only connect to a device its chooser returned")
# A first connection attempt often fails at the link layer on Android
# (status 133, HCI 0x3E "failed to be established"); measured on the
# P4 through its C6 it was about half of them, and the next attempt
# usually works. So try again, up to CONNECT_ATTEMPTS in all.
attempt = 0
while True:
attempt += 1
connection = _WebConnection(self, device, native)
try:
await connection._open(timeout_ms)
except GattError as e:
if attempt >= self.CONNECT_ATTEMPTS or "Connection attempt failed" not in str(e):
raise
self.connect_retries += 1
continue
self._connections.append(connection)
return connection
# The first discovery request makes the browser walk the peer's whole GATT
# table, which took over 2 s (nus's default) from Chrome on Windows to the P4.
# Discovery timeouts shorter than this are raised to it.
DISCOVERY_FLOOR_MS = 10000
def _discovery_timeout(timeout_ms):
return None if timeout_ms is None else max(timeout_ms, DISCOVERY_FLOOR_MS)
class _WebConnection(Connection):
def __init__(self, ble, device, native):
Connection.__init__(self, ble, device, "central")
self._native = native
self._server = None
self._down = asyncio.Event()
self._closed = False
self._characteristics = []
self._lock = asyncio.Lock()
self._mtu = ble.link_mtu
self._on_disconnect = _proxy(self._disconnected_event)
self._listener = None
def _disconnected_event(self, *args):
self._drop()
def _drop(self):
if self._closed:
return
self._closed = True
self._down.set()
for characteristic in self._characteristics:
characteristic._wake()
try:
_h().unlisten(self._native, "gattserverdisconnected", self._listener)
except Exception:
pass
try:
self._ble._connections.remove(self)
except ValueError:
pass
async def _open(self, timeout_ms):
self._listener = _h().listen(self._native, "gattserverdisconnected", self._on_disconnect)
try:
self._server = await _await(self._native.gatt.connect(), "connect", None, timeout_ms)
except BLETimeoutError:
try:
self._native.gatt.disconnect()
except Exception:
pass
self._drop()
raise
except BaseException:
self._drop()
raise
def is_connected(self):
if self._closed or self._server is None:
return False
try:
return bool(self._native.gatt.connected)
except Exception:
return False
async def disconnect(self, timeout_ms=2000):
if not self._closed:
try:
self._native.gatt.disconnect()
except Exception:
pass
# Chrome fires gattserverdisconnected for a local disconnect too,
# but don't depend on it.
try:
await wait_ms(self._down.wait(), timeout_ms, "disconnect")
except BLETimeoutError:
pass
self._drop()
async def disconnected(self, timeout_ms=None):
if not self._closed:
await wait_ms(self._down.wait(), timeout_ms, "disconnected")
def _live(self, what):
if not self.is_connected():
raise DisconnectedError("{}: not connected".format(what))
async def _gatt(self, promise_fn, what, timeout_ms=None):
# Chrome rejects a second GATT operation while one is in flight
# ("GATT operation already in progress"), so run them one at a time.
self._live(what)
async with self._lock:
self._live(what)
return await _await(promise_fn(), what, self, timeout_ms)
async def _discover_services(self, uuid, timeout_ms):
timeout_ms = _discovery_timeout(timeout_ms)
server = self._server
try:
if uuid is None:
found = await self._gatt(lambda: server.getPrimaryServices(), "service discovery", timeout_ms)
else:
found = await self._gatt(
lambda: server.getPrimaryServices(str(uuid)), "service discovery", timeout_ms
)
except BLEError as e:
# Nothing matching, or a service the page didn't ask for: the
# browser's two ways of saying there is none it will show us.
if "NotFoundError" in str(e):
return []
if "SecurityError" in str(e):
raise BLEError(
"{} (list the service in find()'s filter or WebBLE(services=[...]))".format(e)
)
raise
# Browsers expose no handles. Chrome returns services in discovery
# order, which is the server's.
return [_WebClientService(self, s) for s in _items(found)]
class _WebClientService(ClientService):
def __init__(self, connection, native):
ClientService.__init__(self, connection, str(native.uuid))
self._native = native
async def _discover_characteristics(self, uuid, timeout_ms):
timeout_ms = _discovery_timeout(timeout_ms)
native = self._native
try:
if uuid is None:
found = await self.connection._gatt(
lambda: native.getCharacteristics(), "characteristic discovery", timeout_ms
)
else:
found = await self.connection._gatt(
lambda: native.getCharacteristics(str(uuid)), "characteristic discovery", timeout_ms
)
except BLEError as e:
if "NotFoundError" in str(e):
return []
raise
return [_WebClientCharacteristic(self, c) for c in _items(found)]
class _WebClientCharacteristic(ClientCharacteristic):
def __init__(self, service, native):
ClientCharacteristic.__init__(self, service, str(native.uuid), int(_h().props(native)))
self._native = native
self._notify_queue = []
self._indicate_queue = []
self._overrun = 0
self._event = asyncio.Event()
self._listener = None
self._on_value = _proxy(self._value_event)
self._route_indications = False
service.connection._characteristics.append(self)
def _value_event(self, text):
queue = self._indicate_queue if self._route_indications else self._notify_queue
if len(queue) >= self.connection._ble.queue_limit:
self._overrun += 1
else:
queue.append(_from_hex(text))
self._event.set()
def _wake(self):
self._event.set()
async def read(self, timeout_ms=1000):
self._check(FLAG_READ, "read")
native = self._native
view = await self.connection._gatt(lambda: native.readValue(), "read", timeout_ms)
return _from_hex(_h().hex(view))
async def write(self, data, response=None, timeout_ms=1000):
data = bytes(data)
response = self._want_response(response)
self.connection._live("write")
limit = self.connection.mtu - 3
if len(data) > limit:
raise BLEError(
"write of {} bytes exceeds the ATT payload of {} (mtu {} - 3)".format(
len(data), limit, self.connection.mtu
)
)
native = self._native
value = _to_js_bytes(data)
if response:
await self.connection._gatt(lambda: native.writeValueWithResponse(value), "write", timeout_ms)
else:
await self.connection._gatt(lambda: native.writeValueWithoutResponse(value), "write", timeout_ms)
async def subscribe(self, notify=True, indicate=False):
if notify:
self._check(FLAG_NOTIFY, "notify")
if indicate:
self._check(FLAG_INDICATE, "indicate")
if notify and indicate:
raise UnsupportedError(
"a browser subscribes to notifications or indications, not both"
)
native = self._native
if not notify and not indicate:
await self.connection._gatt(lambda: native.stopNotifications(), "unsubscribe")
if self._listener is not None:
_h().unlisten(native, "characteristicvaluechanged", self._listener)
self._listener = None
return
if notify is False and self.properties & FLAG_NOTIFY:
# startNotifications() picks notifications whenever the
# characteristic has them, so it can't be asked for indications.
raise UnsupportedError("a browser can't choose indications on a characteristic that also notifies")
self._route_indications = not notify
# Listen first, so nothing that arrives as the subscription lands is lost.
if self._listener is None:
self._listener = _h().listen(native, "characteristicvaluechanged", self._on_value)
await self.connection._gatt(lambda: native.startNotifications(), "subscribe")
async def _next(self, queue, timeout_ms, what):
if timeout_ms is None:
return await self._take(queue, what)
return await wait_ms(self._take(queue, what), timeout_ms, what)
async def _take(self, queue, what):
while True:
if self._overrun:
raise BLEError(
"{} queue for {} overran: {} dropped because the reader fell {} behind".format(
what, self.uuid, self._overrun, self.connection._ble.queue_limit
)
)
if queue:
return queue.pop(0)
if not self.connection.is_connected():
raise DisconnectedError("{}: disconnected".format(what))
self._event.clear()
await self._event.wait()
async def notified(self, timeout_ms=None):
self._check(FLAG_NOTIFY, "notify")
return await self._next(self._notify_queue, timeout_ms, "notified")
async def indicated(self, timeout_ms=None):
self._check(FLAG_INDICATE, "indicate")
return await self._next(self._indicate_queue, timeout_ms, "indicated")