bledev.midi

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.

bledev.midi.MTU = 247

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.

bledev.midi.QUEUE_LIMIT = 1024

Received messages a port keeps for a reader that isn’t reading.

class bledev.midi.PortInfo(id, name, direction)

Bases: tuple

What Port.info is: the same fields midiports.PortInfo has.

direction

Alias for field number 2

id

Alias for field number 0

name

Alias for field number 1

bledev.midi.now_ms()[source]

This host’s BLE-MIDI clock: milliseconds, 13 bits.

class bledev.midi.Port(connection, name, *, queue_limit=1024, running_status=True)[source]

Bases: object

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.

readinto(buf, nbytes=None)[source]

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.

read(nbytes=None)[source]

Up to nbytes waiting MIDI bytes (everything waiting when None), whole messages only as readinto says, or None.

any()[source]

How many MIDI bytes are waiting to be read.

take()[source]

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.

async receive(timeout_ms=None)[source]

The next (timestamp, message). Raises DisconnectedError once the link has closed and everything that arrived is read.

write(buf, nbytes=None)[source]

Send the first nbytes of buf (all of it when None); returns how many bytes it took. The radio gets them from a task.

send(message, timestamp=None)[source]

Queue one complete message, optionally with its own timestamp.

async drain()[source]

Wait until everything written has been handed to the radio.

close()[source]

Close the port and drop the link.

deinit()

Close the port and drop the link.

async aclose()[source]

Close the port and wait for the disconnect.

async bledev.midi.serve(ble, name=None, *, timeout_ms=None, interval_us=100000, mtu=247, **options)[source]

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.

async bledev.midi.connect(ble, name=None, *, device=None, timeout_ms=10000, mtu=247, queue_limit=1024, running_status=True, **connect_options)[source]

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.