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:
tupleWhat
Port.infois: the same fieldsmidiports.PortInfohas.- direction
Alias for field number 2
- id
Alias for field number 0
- name
Alias for field number 1
- class bledev.midi.Port(connection, name, *, queue_limit=1024, running_status=True)[source]
Bases:
objectOne BLE-MIDI link, as a MIDI port. Made by
serveorconnect.It is both ports
adafruit_miditakes:read,readintoandanyon the way in,writeon 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 orread(), not both.overflowedturns true if more thanqueue_limitmessages waited unread; they are counted indropped, not lost silently.- readinto(buf, nbytes=None)[source]
Waiting MIDI bytes into
buf(at mostnbytes); how many, orNonewhen 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_midi1.6.0 throws away a SysEx that arrives in two reads, so give itsMIDIanin_buf_sizebigger 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
nbyteswaiting MIDI bytes (everything waiting whenNone), whole messages only asreadintosays, orNone.
- take()[source]
The next
(timestamp, message)if one has arrived, elseNone:receivewithout waiting, for a loop that polls. Use one oftake,receiveandread, not two.
- async receive(timeout_ms=None)[source]
The next
(timestamp, message). RaisesDisconnectedErroronce the link has closed and everything that arrived is read.
- write(buf, nbytes=None)[source]
Send the first
nbytesofbuf(all of it whenNone); 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.
- deinit()
Close the port and drop the link.
- 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 aPortwhen 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 aPort.connect_optionsgo todevice.connect(): on a board,min_conn_interval_us=7500, max_conn_interval_us=7500asks for the shortest connection interval, which is what a MIDI link wants.