#include <MIDI_Interfaces/BluetoothMIDI_Interface.hpp>

Detailed Description

A class for MIDI interfaces sending MIDI messages over a Bluetooth Low Energy (BLE) connection.

Configures the Arduino as a BLE peripheral.

See also: MIDI over USB for a list of supported boards; MIDI over BLE for more information and a list of backends

Examples: BLEMIDI-Adapter.ino, and VU-Meter-Bridge.ino.

Definition at line 77 of file BluetoothMIDI_Interface.hpp.

Inheritance diagram for BluetoothMIDI_Interface:

Collaboration diagram for BluetoothMIDI_Interface:

BLE configuration options
BLESettings	ble_settings
	BLE backend configuration option.

void	setName (const char *name)
	Set the BLE device name.

void	setTimeout (std::chrono::milliseconds timeout)
	Set the timeout, the number of milliseconds to buffer the outgoing MIDI messages.

Default MIDI Interfaces
static MIDI_Interface *	getDefault ()
	Return the default MIDI interface.

void	setAsDefault ()
	Set this MIDI interface as the default interface.

Main initialization and updating methods
static void	beginAll ()
	Begin all enabled instances of this class.

static void	updateAll ()
	Update all enabled instances of this class.

Enabling and disabling updatables
static void	enable (UpdatableCRTP *element)
	Enable this updatable: insert it into the linked list of instances, so it gets updated automatically.

static void	enable (UpdatableCRTP &element)
	Enable this updatable: insert it into the linked list of instances, so it gets updated automatically.

template<class U , size_t N>
static void	enable (U(&array)[N])
	Enable this updatable: insert it into the linked list of instances, so it gets updated automatically.

static void	disable (UpdatableCRTP *element)
	Disable this updatable: remove it from the linked list of instances, so it no longer gets updated automatically.

static void	disable (UpdatableCRTP &element)
	Disable this updatable: remove it from the linked list of instances, so it no longer gets updated automatically.

template<class U , size_t N>
static void	disable (U(&array)[N])
	Disable this updatable: remove it from the linked list of instances, so it no longer gets updated automatically.

void	enable ()
	Enable this updatable: insert it into the linked list of instances, so it gets updated automatically.

void	disable ()
	Disable this updatable: remove it from the linked list of instances, so it no longer gets updated automatically.

bool	isEnabled () const
	Check if this updatable is enabled.

void	moveDown ()
	Move down this element in the list.

Initialization and polling
void	begin () override
	Initialize the BLE hardware and start advertising as a MIDI over BLE peripheral.

void	end ()

void	update () override
	Poll the backend (if necessary) and invoke the callbacks for any received MIDI messages, as well as sending them over the pipes connected to this interface.

bool	isConnected () const
	Returns true if a BLE central is currently connected.

Reading incoming MIDI messages
MIDIReadEvent	read ()
	Try reading and parsing a single incoming MIDI message.

ChannelMessage	getChannelMessage () const
	Return the received channel voice message.

SysCommonMessage	getSysCommonMessage () const
	Return the received system common message.

RealTimeMessage	getRealTimeMessage () const
	Return the received real-time message.

SysExMessage	getSysExMessage () const
	Return the received system exclusive message.

uint16_t	getTimestamp () const
	Get the BLE-MIDI timestamp of the latest MIDI message.

MIDI Input Callbacks
void	setCallbacks (MIDI_Callbacks *cb)
	Set the callbacks that will be called when a MIDI message is received.

void	setCallbacks (MIDI_Callbacks &cb)
	Set the callbacks that will be called when a MIDI message is received.

Connecting and disconnecting MIDI Pipes
void	connectSourcePipe (MIDI_Pipe *source)
	Fully connect a source pipe to this sink.

void	disconnectSourcePipes ()
	Disconnect all source pipes that sink to this sink (recursively).

bool	disconnect (TrueMIDI_Source &source)
	Disconnect the given source from this sink.

bool	disconnect (MIDI_Pipe &)=delete

bool	hasSourcePipe () const
	Check if this sink is connected to a source pipe.

MIDI_Pipe *	getSourcePipe () const
	Get a pointer to the pipe this sink is connected to, or `nullptr` if not connected.

Connecting and disconnecting MIDI Pipes
bool	disconnect (TrueMIDI_Sink &sink)
	Disconnect the given sink from this source.

bool	disconnect (MIDI_Pipe &)=delete

void	connectSinkPipe (MIDI_Pipe *sink)
	Fully connect a sink pipe to this source.

void	disconnectSinkPipes ()
	Disconnect all sink pipes that this source sinks to (recursively).

bool	hasSinkPipe () const
	Check if this source is connected to a sink pipe.

MIDI_Pipe *	getSinkPipe ()
	Get a pointer to the pipe this source is connected to, or `nullptr` if not connected.

Sending data over a MIDI Pipe
void	sourceMIDItoPipe (ChannelMessage)
	Send a MIDI Channel Message down the pipe.

void	sourceMIDItoPipe (SysExMessage)
	Send a MIDI System Exclusive message down the pipe.

void	sourceMIDItoPipe (SysCommonMessage)
	Send a MIDI System Common message down the pipe.

void	sourceMIDItoPipe (RealTimeMessage)
	Send a MIDI Real-Time message down the pipe.

Stalling the sink pipes and exclusive access
void	stall (MIDIStaller *cause=eternal_stall)
	Stall this MIDI source.

void	unstall (MIDIStaller *cause=eternal_stall)
	Un-stall the pipes connected to this source, so other sources are allowed to send again.

bool	isStalled () const
	Check if this source can write to the sinks it connects to.

MIDIStaller *	getStaller () const
	Get a pointer to whatever is causing this MIDI source to be stalled.

const char *	getStallerName () const
	Get the name of whatever is causing this MIDI source to be stalled.

void	handleStallers () const
	Give the code that is stalling the MIDI sink pipes the opportunity to do its job and un-stall the pipes.

Sending MIDI Channel Voice messages
void	send (ChannelMessage message)
	Send a MIDI Channel Voice message.

void	sendChannelMessage (MIDIMessageType m, Channel c, uint8_t d1, uint8_t d2, Cable cable=Cable_1)
	Send a 3-byte MIDI Channel Voice message.

void	sendChannelMessage (MIDIMessageType m, Channel c, uint8_t d1, Cable cable=Cable_1)
	Send a 2-byte MIDI Channel Voice message.

void	sendNoteOn (MIDIAddress address, uint8_t velocity)
	Send a MIDI Note On event.

void	sendNoteOff (MIDIAddress address, uint8_t velocity)
	Send a MIDI Note Off event.

void	sendKeyPressure (MIDIAddress address, uint8_t pressure)
	Send a MIDI Key Pressure event.

void	sendControlChange (MIDIAddress address, uint8_t value)
	Send a MIDI Control Change event.

void	sendProgramChange (MIDIAddress address)
	Send a MIDI Program Change event.

void	sendProgramChange (MIDIChannelCable address, uint8_t value)
	Send a MIDI Program Change event.

void	sendChannelPressure (MIDIChannelCable address, uint8_t pressure)
	Send a MIDI Channel Pressure event.

void	sendPitchBend (MIDIChannelCable address, uint16_t value)
	Send a MIDI Pitch Bend event.

Sending MIDI System Common messages
void	send (SysCommonMessage message)
	Send a MIDI System Common message.

void	sendSysCommon (MIDIMessageType m, Cable cable=Cable_1)
	Send a MIDI System Common message.

void	sendSysCommon (MIDIMessageType m, uint8_t data1, Cable cable=Cable_1)
	Send a MIDI System Common message.

void	sendSysCommon (MIDIMessageType m, uint8_t data1, uint8_t data2, Cable cable=Cable_1)
	Send a MIDI System Common message.

void	sendMTCQuarterFrame (uint8_t data, Cable cable=Cable_1)
	Send a MIDI Time Code Quarter Frame.

void	sendMTCQuarterFrame (uint8_t messageType, uint8_t values, Cable cable=Cable_1)
	Send a MIDI Time Code Quarter Frame.

void	sendSongPositionPointer (uint16_t spp, Cable cable=Cable_1)
	Send a MIDI Song Position Pointer message.

void	sendSongSelect (uint8_t song, Cable cable=Cable_1)
	Send a MIDI Song Select message.

void	sendTuneRequest (Cable cable=Cable_1)
	Send a MIDI Tune Request.

Sending MIDI System Exclusive messages
void	send (SysExMessage message)
	Send a MIDI System Exclusive message.

void	sendSysEx (const uint8_t(&sysexdata)[N], Cable cable=Cable_1)
	Send a MIDI System Exclusive message.

void	sendSysEx (const uint8_t *data, uint16_t length, Cable cable=Cable_1)
	Send a MIDI System Exclusive message.

Sending MIDI Real-Time messages
void	send (RealTimeMessage message)
	Send a MIDI Real-Time message.

void	sendRealTime (MIDIMessageType rt, Cable cable=Cable_1)
	Send a MIDI Real-Time message.

void	sendRealTime (uint8_t rt, Cable cable=Cable_1)
	Send a MIDI Real-Time message.

void	sendTimingClock (Cable cable=Cable_1)
	Send a MIDI Timing Clock message.

void	sendStart (Cable cable=Cable_1)
	Send a MIDI Start message.

void	sendContinue (Cable cable=Cable_1)
	Send a MIDI Continue message.

void	sendStop (Cable cable=Cable_1)
	Send a MIDI Stop message.

void	sendActiveSensing (Cable cable=Cable_1)
	Send a MIDI Active Sensing message.

void	sendSystemReset (Cable cable=Cable_1)
	Send a MIDI System Reset message.

Flushing the MIDI send buffer
void	sendNow ()
	Causes all buffered messages to be sent immediately.

Deprecated
void	sendKP (MIDIAddress address, uint8_t pressure)
	Send a MIDI Key Pressure event.

void	sendCC (MIDIAddress address, uint8_t value)
	Send a MIDI Control Change event.

void	sendPC (MIDIAddress address)
	Send a MIDI Program Change event.

void	sendPC (MIDIChannelCable address, uint8_t value)
	Send a MIDI Program Change event.

void	sendCP (MIDIChannelCable address, uint8_t pressure)
	Send a MIDI Channel Pressure event.

void	sendPB (MIDIChannelCable address, uint16_t value)
	Send a MIDI Pitch Bend event.

Static Public Member Functions
template<class MIDIInterface_t >
static void	handleStall (MIDIInterface_t *self)
	Un-stall the given MIDI interface.

template<class MIDIInterface_t >
static void	updateIncoming (MIDIInterface_t *iface)
	Read, parse and dispatch incoming MIDI messages on the given interface.

template<class MIDIInterface_t >
static void	dispatchIncoming (MIDIInterface_t *iface, MIDIReadEvent event)
	Dispatch the given type of MIDI message from the given interface.

static void	swap (MIDI_Sink &a, MIDI_Sink &b)

static void	swap (MIDI_Source &a, MIDI_Source &b)

Public Attributes
BLEMIDIBackend	backend
	Low-level BLE backend for sending and receiving MIDI over BLE packets.

Protected Member Functions
void	sinkMIDIfromPipe (ChannelMessage msg) override
	Accept an incoming MIDI Channel message from the source pipe.

void	sinkMIDIfromPipe (SysExMessage msg) override
	Accept an incoming MIDI System Exclusive message from the source pipe.

void	sinkMIDIfromPipe (SysCommonMessage msg) override
	Accept an incoming MIDI System Common message from the source pipe.

void	sinkMIDIfromPipe (RealTimeMessage msg) override
	Accept an incoming MIDI Real-Time message from the source pipe.

void	onChannelMessage (ChannelMessage message)
	Call the channel message callback and send the message to the sink pipe.

void	onSysExMessage (SysExMessage message)
	Call the SysEx message callback and send the message to the sink pipe.

void	onSysCommonMessage (SysCommonMessage message)
	Call the System Common message callback and send the message to the sink pipe.

void	onRealTimeMessage (RealTimeMessage message)
	Call the real-time message callback and send the message to the sink pipe.

Static Protected Member Functions
static const char *	getNameNull (MIDIStaller *s)
	Get the staller's name for debugging purposes.

Protected Attributes
MIDI_Pipe *	sourcePipe = nullptr

MIDI_Pipe *	sinkPipe = nullptr

Derived *	next

Derived *	previous

Static Protected Attributes
static DoublyLinkedList< Derived >	updatables

Private Member Functions
void	sendImpl (L &lck, F add_to_buffer)

void	sendChannelMessageImpl (ChannelMessage) override
	Low-level function for sending a MIDI channel voice message.

void	sendSysCommonImpl (SysCommonMessage) override
	Low-level function for sending a MIDI system common message.

void	sendSysExImpl (SysExMessage) override
	Low-level function for sending a system exclusive MIDI message.

void	sendRealTimeImpl (RealTimeMessage) override
	Low-level function for sending a MIDI real-time message.

void	sendNowImpl () override
	Low-level function for sending any buffered outgoing MIDI messages.

void	handleStall () override
	Call back that should finish any MIDI messages that are in progress, and un-stall the pipe or MIDI source as quickly as possible.

const char *	getName () const override
	Get the staller's name for debugging purposes.

virtual void	stallDownstream (MIDIStaller , MIDI_Source )
	Base case for recursive stall function.

virtual void	unstallDownstream (MIDIStaller , MIDI_Source )
	Base case for recursive un-stall function.

virtual MIDI_Sink *	getFinalSink ()
	Base case for recursive function.

void	disconnectSourcePipesShallow ()
	Disconnect only the first pipe connected to this sink.

virtual void	stallUpstream (MIDIStaller , MIDI_Sink )
	Base case for recursive stall function.

virtual void	unstallUpstream (MIDIStaller , MIDI_Sink )
	Base case for recursive un-stall function.

virtual MIDI_Source *	getInitialSource ()
	Base case for recursive function.

void	disconnectSinkPipesShallow ()
	Disconnect only the first pipe connected to this source.

Private Attributes
Backend::IncomingMIDIMessage	incomingMessage
	Incoming message that can be from retrieved using the `getChannelMessage()`, `getSysCommonMessage()`, `getRealTimeMessage()` and `getSysExMessage()` methods.

MIDI_Callbacks *	callbacks = nullptr

Static Private Attributes
static MIDI_Interface *	DefaultMIDI_Interface = nullptr

Member Function Documentation

◆ sendImpl()

void sendImpl	(	L &	lck,
		F	add_to_buffer )

privateinherited