Source code for bledev.auto

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""Optional backend selection. Nothing in bledev imports this module.

    import bledev.auto
    ble = bledev.auto.adapter()

picks, in order: ``mpble`` where MicroPython's ``bluetooth`` module exists,
``cpble`` where CircuitPython's ``_bleio`` does, ``webble`` in a browser (PyScript, Pyodide, the Workbench simulator), and
``bleak`` on CPython when bleak is installed (``pip install omnipython[ble]``).
Pass ``backend="fake"`` (or set ``BLEDEV_BACKEND``) to force one; extra
keyword arguments go to the backend's constructor.

A host with none raises `bledev.UnsupportedError` saying what to install.
"""

import sys

from . import UnsupportedError

#: backend name -> (module, class). Each module stands alone and never imports this one.
BACKENDS = {
    "mpble": ("bledev.mpble", "MPBLE"),
    "cpble": ("bledev.cpble", "CPBLE"),
    "bleak": ("bledev.bleak", "BleakBLE"),
    "webble": ("bledev.webble", "WebBLE"),
    "fake": ("bledev.fake", "FakeBLE"),
}


def _importable(name):
    try:
        __import__(name)
        return True
    except Exception:
        return False


def _in_browser():
    if sys.platform in ("emscripten", "webassembly"):
        return True
    return _importable("_wasm_bridge") or _importable("pyodide")


[docs] def backend_name(): """The backend this host would get, or ``None`` if it has no BLE.""" impl = getattr(sys, "implementation", None) impl = getattr(impl, "name", "") if impl in ("micropython", "circuitpython"): if _in_browser(): return "webble" if _importable("bluetooth"): return "mpble" if _importable("_bleio"): return "cpble" return None if _in_browser(): return "webble" if _importable("bleak"): return "bleak" return None
def _env_backend(): try: import os return os.getenv("BLEDEV_BACKEND") except Exception: return None
[docs] def adapter(backend=None, **kwargs): """Construct the adapter for this host (or for ``backend``).""" name = backend or _env_backend() or backend_name() if name is None: raise UnsupportedError( "no BLE backend on this host: on CPython, pip install 'omnipython[ble]' " "for bleak; on MicroPython, use firmware built with bluetooth; on " "CircuitPython, a board with _bleio" ) if name not in BACKENDS: raise UnsupportedError("unknown bledev backend {!r}; one of {}".format(name, sorted(BACKENDS))) module_name, class_name = BACKENDS[name] module = __import__(module_name, None, None, [class_name]) return getattr(module, class_name)(**kwargs)