Source code for bledev.midi

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

"""MIDI over Bluetooth LE (BLE-MIDI 1.0), as a MIDI port.

The board advertises the standard BLE-MIDI service; a laptop, a phone, a DAW
or another board connects::

    import bledev.midi as midi

    port = await midi.serve(ble, name="rack")    # on the board
    port = await midi.connect(ble, name="rack")  # anywhere that can be a central

Either way you get a `Port`: one object that is both the input and
the output port ``adafruit_midi`` wants, in the shape of CircuitPython's
``usb_midi`` ports (the contract the ``midiports`` package documents). So the
script you run over USB or a 5-pin cable runs over BLE with only the line
that opens the port changed::

    import adafruit_midi

    midi = adafruit_midi.MIDI(midi_in=port, midi_out=port)

``read(nbytes)`` returns plain MIDI 1.0 bytes or ``None`` and never blocks,
``readinto(buf, nbytes)`` does the same into your buffer without allocating,
``any()`` says how many bytes wait, and ``write(buf, nbytes)`` sends. Every
message comes out whole, with its status byte, so ``adafruit_midi`` (which
reads no running status) parses all of it. BLE-MIDI's packets, timestamps,
running status and SysEx fragments stay inside; the codec is
`bledev.midi_codec`. For the sender's timestamps as well,
``await port.receive()`` returns ``(timestamp, message)``.

The characteristic accepts writes with and without response and notifies, as
the BLE-MIDI specification asks, and reads back empty. Every device and host
that speaks BLE-MIDI (macOS and iOS, Android, Windows MIDI Services, BLE-MIDI
controllers) uses the same two UUIDs.
"""

import sys

import asyncio

import boarddev

from . import (
    BLEError,
    BLETimeoutError,
    BusyError,
    Characteristic,
    DisconnectedError,
    MAX_MTU,
    Service,
    UnsupportedError,
    UUID,
    connect_and_set_up,
    is_adapter,
    sleep_ms,
    wait_ms,
)
from .midi_codec import TIMESTAMP_MASK, Decoder, Encoder, Splitter

SERVICE = UUID("03b80e5a-ede8-4b33-a751-6ce34ec4c700")
CHARACTERISTIC = UUID("7772e5db-3868-4112-a1a9-f2669d106bf3")

#: The ATT MTU both sides ask for. A note is 5 bytes on the air, so this
#: only matters for SysEx and bursts; it's nus's value, for the same reason.
MTU = 247

#: Received messages a port keeps for a reader that isn't reading.
QUEUE_LIMIT = 1024

_POLL_MS = 50
_BUSY_WAIT_MS = 1

# ---------------------------------------------------------------- the port contract

IN = "in"
OUT = "out"
INOUT = "inout"

try:
    from collections import namedtuple
except ImportError:  # pragma: no cover
    from ucollections import namedtuple

#: What :attr:`Port.info` is: the same fields ``midiports.PortInfo`` has.
PortInfo = namedtuple("PortInfo", "id name direction")


if sys.implementation.name == "micropython":
    import time

    def now_ms():
        """This host's BLE-MIDI clock: milliseconds, 13 bits."""
        return time.ticks_ms() & TIMESTAMP_MASK

elif sys.implementation.name == "circuitpython":
    # time.monotonic() is a float that loses milliseconds after a few hours.
    try:
        from supervisor import ticks_ms as _ticks_ms
    except ImportError:  # the unix port has no supervisor, and MicroPython's time
        from time import ticks_ms as _ticks_ms

    def now_ms():
        """This host's BLE-MIDI clock: milliseconds, 13 bits."""
        return _ticks_ms() & TIMESTAMP_MASK

else:
    import time

[docs] def now_ms(): """This host's BLE-MIDI clock: milliseconds, 13 bits.""" return int(time.monotonic() * 1000) & TIMESTAMP_MASK
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
[docs] class Port: """One BLE-MIDI link, as a MIDI port. Made by `serve` or `connect`. It is both ports ``adafruit_midi`` takes: ``read``, ``readinto`` and ``any`` on the way in, ``write`` on the way out, plain MIDI bytes, never blocking. Writes are sent from a task, packed into as few packets as the link allows, so the app needs a running asyncio loop, as everything in bledev does. ``await drain()`` waits until they're on the air. ``await receive()`` returns the next ``(timestamp, message)``; the timestamp is the sender's 13-bit millisecond clock. Use it or ``read()``, not both. ``overflowed`` turns true if more than ``queue_limit`` messages waited unread; they are counted in ``dropped``, not lost silently. """ def __init__(self, connection, name, *, queue_limit=QUEUE_LIMIT, running_status=True): self.info = PortInfo("ble:" + connection.device.address, name, INOUT) self.direction = INOUT self.is_open = True self.connection = connection self.queue_limit = queue_limit self.dropped = 0 self.decode_errors = 0 self.messages_in = 0 self.messages_out = 0 self._messages = [] self._pending = b"" # the message being read out, from _pos on self._pos = 0 self._waiting = 0 # bytes queued, for any() self._scratch = bytearray(64) self._view = memoryview(self._scratch) self._arrived = asyncio.Event() self._decoder = Decoder() self._encoder = Encoder(running_status) self._splitter = Splitter() self._wake = asyncio.Event() self._idle = asyncio.Event() self._idle.set() self._send_error = None self._closed = False self._sender = asyncio.create_task(self._send_loop()) @property def overflowed(self): return self.dropped > 0 # -- receiving def _packet(self, data): messages = self._decoder.decode(data) self.decode_errors = self._decoder.errors for item in messages: if len(self._messages) >= self.queue_limit: self.dropped += 1 else: self._messages.append(item) self._waiting += len(item[1]) self.messages_in += 1 if messages: self._arrived.set() def _check_open(self): if not self.is_open: raise OSError("MIDI port is closed")
[docs] def readinto(self, buf, nbytes=None): """Waiting MIDI bytes into ``buf`` (at most ``nbytes``); how many, or ``None`` when nothing has arrived. Never blocks, allocates nothing. Only whole messages are taken, as many as fit, so a long SysEx is never handed out in pieces when the buffer has room for it. ``adafruit_midi`` 1.6.0 throws away a SysEx that arrives in two reads, so give its ``MIDI`` an ``in_buf_size`` bigger than your longest SysEx. A message bigger than the whole buffer still comes out in parts, the rest on the next call. """ self._check_open() size = len(buf) if nbytes is None or nbytes > len(buf) else nbytes n = 0 while n < size: pending = self._pending pos = self._pos if pos >= len(pending): if not self._messages: break if n and len(self._messages[0][1]) > size - n: break # the next message won't fit whole: leave it for the next read pending = self._pending = self._messages.pop(0)[1] pos = 0 end = min(len(pending), pos + size - n) while pos < end: buf[n] = pending[pos] n += 1 pos += 1 self._pos = pos self._waiting -= n return n or None
[docs] def read(self, nbytes=None): """Up to ``nbytes`` waiting MIDI bytes (everything waiting when ``None``), whole messages only as `readinto` says, or ``None``.""" want = self._waiting if nbytes is None else min(nbytes, self._waiting) if want <= 0: self._check_open() return None if want > len(self._scratch): self._scratch = bytearray(want) self._view = memoryview(self._scratch) n = self.readinto(self._view, want) return bytes(self._view[:n]) if n else None
[docs] def any(self): """How many MIDI bytes are waiting to be read.""" return self._waiting
[docs] def take(self): """The next ``(timestamp, message)`` if one has arrived, else ``None``: `receive` without waiting, for a loop that polls. Use one of ``take``, ``receive`` and ``read``, not two.""" if not self._messages: return None item = self._messages.pop(0) self._waiting -= len(item[1]) return item
[docs] async def receive(self, timeout_ms=None): """The next ``(timestamp, message)``. Raises `DisconnectedError` once the link has closed and everything that arrived is read.""" while True: if self._messages: item = self._messages.pop(0) self._waiting -= len(item[1]) return item if self._closed or not self.connection.is_connected(): raise DisconnectedError("MIDI link closed") self._arrived.clear() await wait_ms(self._any_news(), timeout_ms, "receive")
async def _any_news(self): await self._arrived.wait() def __aiter__(self): return self async def __anext__(self): try: return await self.receive() except DisconnectedError: raise StopAsyncIteration # -- sending
[docs] def write(self, buf, nbytes=None): """Send the first ``nbytes`` of ``buf`` (all of it when ``None``); returns how many bytes it took. The radio gets them from a task.""" self._check_open() data = buf if nbytes is None or nbytes >= len(buf) else buf[:nbytes] if self._send_error is not None: raise self._send_error if not self.connection.is_connected(): raise DisconnectedError("MIDI link closed") ts = now_ms() count = 0 for message in self._splitter.feed(data): self._encoder.put(ts, message) count += 1 if count: self.messages_out += count self._idle.clear() self._wake.set() return len(data)
[docs] def send(self, message, timestamp=None): """Queue one complete message, optionally with its own timestamp.""" self._check_open() self._encoder.put(now_ms() if timestamp is None else timestamp, message) self.messages_out += 1 self._idle.clear() self._wake.set()
[docs] async def drain(self): """Wait until everything written has been handed to the radio.""" await self._idle.wait() if self._send_error is not None: raise self._send_error
async def _send_loop(self): try: while not self._closed: await self._wake.wait() self._wake.clear() while self._encoder.pending(): packet = self._encoder.packet(self.connection.mtu - 3) await self._send_packet(packet) self._idle.set() except Exception as e: self._send_error = e if isinstance(e, BLEError) else BLEError("MIDI send: {}".format(e)) self._idle.set() async def _send_packet(self, packet): raise NotImplementedError # -- closing
[docs] def close(self): """Close the port and drop the link.""" if not self.is_open: return self.is_open = False self._finish() if self.connection.is_connected(): try: asyncio.create_task(self.connection.disconnect()) except Exception: pass
deinit = close def __enter__(self): return self def __exit__(self, exc_type, exc, traceback): self.close()
[docs] async def aclose(self): """Close the port and wait for the disconnect.""" was_open = self.is_open self.is_open = False self._finish() if was_open and self.connection.is_connected(): await self.connection.disconnect()
def _finish(self): self._closed = True self._wake.set() self._arrived.set()
class _ServerPort(Port): def __init__(self, connection, server, **options): Port.__init__(self, connection, server.name, **options) self._server = server async def _send_packet(self, packet): char = self._server.char while True: try: char.notify(self.connection, packet) return except BusyError: if not self.connection.is_connected(): raise DisconnectedError("MIDI link closed while sending") await sleep_ms(_BUSY_WAIT_MS) class _ClientPort(Port): def __init__(self, connection, char, name, **options): Port.__init__(self, connection, name, **options) self._char = char self._no_response = bool(char.properties & 0x0004) self._receiver = asyncio.create_task(self._receive()) async def _receive(self): try: while True: self._packet(await self._char.notified()) except Exception: pass finally: self._finish() async def _send_packet(self, packet): await self._char.write(packet, response=not self._no_response) class _Server: """The BLE-MIDI service on one adapter, shared by every port it serves.""" def __init__(self, ble, name): self.ble = ble self.name = name self.service = Service(SERVICE) self.char = Characteristic( self.service, CHARACTERISTIC, read=True, write=True, write_no_response=True, notify=True, capture=True, max_len=MAX_MTU - 3, initial=b"", ) self.ports = [] self._task = None def add(self, port): self.ports.append(port) if self._task is None: self._task = asyncio.create_task(self._run()) def _port_for(self, connection): for port in self.ports: if port.connection is connection or port.connection == connection: return port return None def _retire_gone(self): for port in list(self.ports): if port._closed or not port.connection.is_connected(): self.ports.remove(port) port._finish() async def _run(self): try: while self.ports: try: connection, data = await self.char.written(timeout_ms=_POLL_MS) except BLETimeoutError: self._retire_gone() continue port = self._port_for(connection) if port is not None: port._packet(data) finally: self._task = None def _server_for(ble, name, mtu): server = getattr(ble, "_midi_server", None) if server is None: _set_mtu(ble, mtu) server = _Server(ble, name) ble.register_services(server.service) ble._midi_server = server server.name = name return server
[docs] async def serve(ble, name=None, *, timeout_ms=None, interval_us=100000, mtu=MTU, **options): """Advertise BLE-MIDI as ``name`` (default: the board's name, ``boarddev.name()``) and return a `Port` when a central connects. Call it again for the next connection. The service is registered once per adapter, the first time; don't register other services on the same adapter afterwards. """ ble = _adapter(ble) if name is None: name = boarddev.name() server = _server_for(ble, name, mtu) # Hosts that pair (Windows, macOS) name the MIDI port after the GAP device # name, not the advertised one; without this Windows lists "MPY ESP32". try: ble.config(gap_name=name) except (UnsupportedError, ValueError, OSError): pass connection = await ble.advertise(interval_us, name=name, services=[SERVICE], timeout_ms=timeout_ms) port = _ServerPort(connection, server, **options) server.add(port) return port
[docs] async def connect( ble, name=None, *, device=None, timeout_ms=10000, mtu=MTU, queue_limit=QUEUE_LIMIT, running_status=True, **connect_options ): """Find a BLE-MIDI device (by ``name``, or the first one advertising the service), connect, subscribe, and return a `Port`. ``connect_options`` go to ``device.connect()``: on a board, ``min_conn_interval_us=7500, max_conn_interval_us=7500`` asks for the shortest connection interval, which is what a MIDI link wants. """ 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 BLE-MIDI service".format(connection.device)) char = await service.characteristic(CHARACTERISTIC) if char is None: raise BLEError("{!r}: the BLE-MIDI service has no MIDI characteristic".format(connection.device)) await char.subscribe(notify=True) return char connection, char = await connect_and_set_up( ble, setup, name=name, service=SERVICE, device=device, timeout_ms=timeout_ms, **connect_options ) label = name or getattr(connection.device, "name", None) or connection.device.address return _ClientPort(connection, char, label, queue_limit=queue_limit, running_status=running_status)