Source code for bledev.nus

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

"""Nordic UART Service: a two-way byte stream over BLE.

The board advertises and the other side connects::

    import bledev.nus as nus

    link = await nus.serve(ble, name="rack")    # on the board
    link = await nus.connect(ble, name="rack")  # on the laptop, phone or another board

Both return a `Link`, which reads like an asyncio stream::

    await link.write(b"hello\\n")
    line = await link.readline()
    async for line in link:        # lines until the link closes
        ...
    await link.close()

The UUIDs are Nordic's, so nRF Connect, Web Bluetooth serial terminals and
Workbench's Bluetooth transport all speak to it. ``RX`` is what the central
writes; ``TX`` is what the peripheral notifies.

``ble`` is a bledev adapter. A raw MicroPython ``bluetooth.BLE`` is wrapped in
`bledev.mpble.MPBLE` for you.
"""

import asyncio

import boarddev

from . import (
    BLEError,
    BLETimeoutError,
    BusyError,
    Characteristic,
    DisconnectedError,
    MAX_MTU,
    Service,
    UnsupportedError,
    UUID,
    connect_and_set_up,
    is_adapter,
    sleep_ms,
)

SERVICE = UUID("6e400001-b5a3-f393-e0a9-e50e24dcca9e")
RX = UUID("6e400002-b5a3-f393-e0a9-e50e24dcca9e")
TX = UUID("6e400003-b5a3-f393-e0a9-e50e24dcca9e")

#: The ATT MTU both sides ask for. 247 fills one data-length-extended link
#: packet (251 bytes), so a notification carries 244 bytes.
MTU = 247

# How long the server's receive loop waits before checking for links whose
# peer has gone, in milliseconds. A closed link reports end-of-stream only
# after every write that arrived before the disconnect has been read.
_POLL_MS = 50

# How long a send waits after the controller reports its buffers full.
_BUSY_WAIT_MS = 2


def _adapter(ble):
    if is_adapter(ble):
        return ble
    if hasattr(ble, "gap_advertise"):
        from . import mpble

        return mpble.get(ble)
    if hasattr(ble, "start_advertising") and hasattr(ble, "erase_bonding"):
        from . import cpble  # CircuitPython's _bleio.adapter

        return cpble.get(ble)
    raise TypeError("expected a bledev adapter, not {!r}".format(ble))


def _set_mtu(ble, mtu):
    try:
        ble.config(mtu=mtu)
    except UnsupportedError:
        pass






class _ServerLink(Link):
    """The peripheral's end: receives writes on RX, notifies on TX."""

    def __init__(self, connection, server):
        Link.__init__(self, connection)
        self._server = server
        self._peer_gone = False
        self._watch = asyncio.create_task(self._watch_disconnect())

    async def _watch_disconnect(self):
        try:
            await self.connection.disconnected()
        finally:
            # The server loop closes the link once the receive queue is empty,
            # so writes that raced the disconnect are still delivered.
            self._peer_gone = True
            self._server.wake()

    async def _send(self, chunk):
        tx = self._server.tx
        while True:
            try:
                tx.notify(self.connection, chunk)
                return
            except BusyError:
                if not self.connection.is_connected():
                    raise DisconnectedError("link closed while sending")
                await sleep_ms(_BUSY_WAIT_MS)


class _Server:
    """The GATT service on one adapter, shared by every link it serves."""

    def __init__(self, ble):
        self.ble = ble
        self.service = Service(SERVICE)
        self.rx = Characteristic(
            self.service, RX, write=True, write_no_response=True, capture=True, max_len=MAX_MTU - 3
        )
        self.tx = Characteristic(self.service, TX, notify=True)
        self.links = []
        self._task = None

    def add(self, link):
        self.links.append(link)
        if self._task is None:
            self._task = asyncio.create_task(self._run())

    def wake(self):
        pass  # the loop polls; kept so a backend with an event can hook it

    def _link_for(self, connection):
        for link in self.links:
            if link.connection is connection or link.connection == connection:
                return link
        return None

    def _retire_gone(self):
        for link in list(self.links):
            if link._peer_gone:
                self.links.remove(link)
                link._finish()

    async def _run(self):
        try:
            while self.links:
                try:
                    connection, data = await self.rx.written(timeout_ms=_POLL_MS)
                except BLETimeoutError:
                    self._retire_gone()
                    continue
                link = self._link_for(connection)
                if link is not None:
                    link._feed(data)
        except Exception as e:  # a receive queue overrun, most likely
            for link in self.links:
                link._finish(e)
            self.links = []
        finally:
            self._task = None


def _server_for(ble, mtu):
    server = getattr(ble, "_nus_server", None)
    if server is None:
        _set_mtu(ble, mtu)
        server = _Server(ble)
        ble.register_services(server.service)
        ble._nus_server = server
    return server


[docs] async def serve(ble, name=None, *, timeout_ms=None, interval_us=100000, mtu=MTU): """Advertise the Nordic UART service as ``name`` (default: the board's name, ``boarddev.name()``) and return a `Link` when a central connects. Call it again for the next connection; the service is registered once per adapter, so don't register other services on the same adapter afterwards. """ ble = _adapter(ble) if name is None: name = boarddev.name() server = _server_for(ble, mtu) connection = await ble.advertise(interval_us, name=name, services=[SERVICE], timeout_ms=timeout_ms) link = _ServerLink(connection, server) server.add(link) return link
class _ClientLink(Link): """The central's end: writes RX, receives TX notifications.""" def __init__(self, connection, rx, tx): Link.__init__(self, connection) self._rx = rx self._tx = tx self._no_response = bool(rx.properties & 0x0004) self._pump = asyncio.create_task(self._receive()) async def _receive(self): error = None try: while True: self._feed(await self._tx.notified()) except DisconnectedError: pass except Exception as e: error = e finally: self._finish(error) async def _send(self, chunk): await self._rx.write(chunk, response=not self._no_response)
[docs] async def connect(ble, name=None, *, device=None, timeout_ms=10000, mtu=MTU, **connect_options): """Find a NUS peripheral (by ``name``, or the first one advertising the service), connect, and return a `Link`. Pass ``device`` to skip the scan. ``connect_options`` go to ``device.connect()``; on a board, ``min_conn_interval_us`` and ``max_conn_interval_us`` trade power for throughput. """ ble = _adapter(ble) _set_mtu(ble, mtu) async def setup(connection): try: await connection.exchange_mtu(mtu) except (UnsupportedError, BLETimeoutError): pass service = await connection.service(SERVICE) if service is None: raise BLEError("{!r} has no Nordic UART service".format(connection.device)) rx = await service.characteristic(RX) tx = await service.characteristic(TX) if rx is None or tx is None: raise BLEError("{!r}: Nordic UART service is missing RX or TX".format(connection.device)) await tx.subscribe(notify=True) return rx, tx connection, (rx, tx) = await connect_and_set_up( ble, setup, name=name, service=SERVICE, device=device, timeout_ms=timeout_ms, **connect_options ) return _ClientLink(connection, rx, tx)