Control Surface master
MIDI Control Surface library for Arduino
Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | List of all members
BLEMIDIPacketBuilder Class Reference

#include <MIDI_Interfaces/BLEMIDI/BLEMIDIPacketBuilder.hpp>

Detailed Description

Class for building MIDI over Bluetooth Low Energy packets.

Definition at line 10 of file BLEMIDIPacketBuilder.hpp.

+ Collaboration diagram for BLEMIDIPacketBuilder:

Public Member Functions

 BLEMIDIPacketBuilder (size_t capacity=20)
 
void reset ()
 Reset the builder to start a new packet. More...
 
void setCapacity (uint16_t capacity)
 Set the maximum capacity of the buffer. More...
 
uint16_t getSize () const
 Get the size of the current packet. More...
 
const uint8_t * getBuffer () const
 Get a pointer to the packet data buffer. More...
 
bool empty () const
 Check if the packet buffer is empty. More...
 
const std::vector< uint8_t > & getPacket () const
 Return the packet as a vector of bytes. More...
 
bool add3B (uint8_t header, uint8_t data1, uint8_t data2, uint16_t timestamp)
 Try adding a 3-byte MIDI channel voice message to the packet. More...
 
bool add2B (uint8_t header, uint8_t data1, uint16_t timestamp)
 Try adding a 2-byte MIDI channel voice message to the packet. More...
 
bool addRealTime (uint8_t rt, uint16_t timestamp)
 Try adding a MIDI real-time message to the packet. More...
 
bool addSysCommon (uint8_t num_data, uint8_t header, uint8_t data1, uint8_t data2, uint16_t timestamp)
 Try adding a MIDI system common message to the packet. More...
 
bool addSysEx (const uint8_t *&data, size_t &length, uint16_t timestamp)
 Try adding (part of) a SysEx message to the packet. More...
 
void continueSysEx (const uint8_t *&data, size_t &length, uint16_t timestamp)
 Add a SysEx continuation to the packet. More...
 

Private Member Functions

bool hasSpaceFor (size_t bytes) const
 Check if the buffer has space left. More...
 
void initBuffer (uint16_t timestamp)
 If this is the first byte/message in the packet, add the header containing the 6 most significant bits of the timestamp. More...
 
template<bool ThreeBytes>
bool addImpl (uint8_t header, uint8_t data1, uint8_t data2, uint16_t timestamp)
 Try adding a 2-byte or 3-byte MIDI channel voice message to the packet. More...
 

Static Private Member Functions

constexpr static uint8_t getTimestampMSB (uint16_t timestamp)
 Timestamp[0]: 0b10hh hhhh. More...
 
constexpr static uint8_t getTimestampLSB (uint16_t timestamp)
 Timestamp[1]: 0b1lll llll. More...
 

Private Attributes

uint8_t runningHeader = 0
 
uint8_t runningTimestamp = 0
 
std::vector< uint8_t > buffer = std::vector<uint8_t>(0)
 

Static Private Attributes

constexpr static const uint8_t SysExStart
 
constexpr static const uint8_t SysExEnd
 

Constructor & Destructor Documentation

◆ BLEMIDIPacketBuilder()

BLEMIDIPacketBuilder ( size_t  capacity = 20)
inline

Definition at line 69 of file BLEMIDIPacketBuilder.hpp.

Member Function Documentation

◆ hasSpaceFor()

bool hasSpaceFor ( size_t  bytes) const
inlineprivate

Check if the buffer has space left.

Definition at line 22 of file BLEMIDIPacketBuilder.hpp.

◆ getTimestampMSB()

constexpr static uint8_t getTimestampMSB ( uint16_t  timestamp)
inlinestaticconstexprprivate

Timestamp[0]: 0b10hh hhhh.

Definition at line 27 of file BLEMIDIPacketBuilder.hpp.

◆ getTimestampLSB()

constexpr static uint8_t getTimestampLSB ( uint16_t  timestamp)
inlinestaticconstexprprivate

Timestamp[1]: 0b1lll llll.

Definition at line 31 of file BLEMIDIPacketBuilder.hpp.

◆ initBuffer()

void initBuffer ( uint16_t  timestamp)
inlineprivate

If this is the first byte/message in the packet, add the header containing the 6 most significant bits of the timestamp.

Definition at line 37 of file BLEMIDIPacketBuilder.hpp.

◆ addImpl()

bool addImpl ( uint8_t  header,
uint8_t  data1,
uint8_t  data2,
uint16_t  timestamp 
)
private

Try adding a 2-byte or 3-byte MIDI channel voice message to the packet.

Template Parameters
ThreeBytesSet to true for a 3-byte message, false for a 2-byte message.
Parameters
headerMIDI status byte.
data1MIDI data byte 1.
data2MIDI data byte 2 (if ThreeBytes == true).
timestamp13-bit BLE-MIDI timestamp.
Return values
trueSuccessfully added message to the packet.
falseBuffer is too full, send the current packet, reset the packet builder, and try again.

Definition at line 6 of file BLEMIDIPacketBuilder.cpp.

◆ reset()

void reset ( )

Reset the builder to start a new packet.

Definition at line 48 of file BLEMIDIPacketBuilder.cpp.

◆ setCapacity()

void setCapacity ( uint16_t  capacity)

Set the maximum capacity of the buffer.

Set this to the MTU of the BLE link minus three bytes (for notify overhead).

Definition at line 53 of file BLEMIDIPacketBuilder.cpp.

◆ getSize()

uint16_t getSize ( ) const
inline

Get the size of the current packet.

Definition at line 79 of file BLEMIDIPacketBuilder.hpp.

◆ getBuffer()

const uint8_t * getBuffer ( ) const
inline

Get a pointer to the packet data buffer.

Definition at line 81 of file BLEMIDIPacketBuilder.hpp.

◆ empty()

bool empty ( ) const
inline

Check if the packet buffer is empty.

Definition at line 83 of file BLEMIDIPacketBuilder.hpp.

◆ getPacket()

const std::vector< uint8_t > & getPacket ( ) const
inline

Return the packet as a vector of bytes.

Definition at line 86 of file BLEMIDIPacketBuilder.hpp.

◆ add3B()

bool add3B ( uint8_t  header,
uint8_t  data1,
uint8_t  data2,
uint16_t  timestamp 
)

Try adding a 3-byte MIDI channel voice message to the packet.

Parameters
headerMIDI status byte.
data1MIDI data byte 1.
data2MIDI data byte 2.
timestamp13-bit BLE-MIDI timestamp.
Return values
trueSuccessfully added message to the packet.
falseBuffer is too full, send the current packet, reset the packet builder, and try again.

Definition at line 60 of file BLEMIDIPacketBuilder.cpp.

◆ add2B()

bool add2B ( uint8_t  header,
uint8_t  data1,
uint16_t  timestamp 
)

Try adding a 2-byte MIDI channel voice message to the packet.

Parameters
headerMIDI status byte.
data1MIDI data byte 1.
timestamp13-bit BLE-MIDI timestamp.
Return values
trueSuccessfully added message to the packet.
falseBuffer is too full, send the current packet, reset the packet builder, and try again.

Definition at line 66 of file BLEMIDIPacketBuilder.cpp.

◆ addRealTime()

bool addRealTime ( uint8_t  rt,
uint16_t  timestamp 
)

Try adding a MIDI real-time message to the packet.

Parameters
rtMIDI real-time byte.
timestamp13-bit BLE-MIDI timestamp.
Return values
trueSuccessfully added message to the packet.
falseBuffer is too full, send the current packet, reset the packet builder, and try again.

Definition at line 72 of file BLEMIDIPacketBuilder.cpp.

◆ addSysCommon()

bool addSysCommon ( uint8_t  num_data,
uint8_t  header,
uint8_t  data1,
uint8_t  data2,
uint16_t  timestamp 
)

Try adding a MIDI system common message to the packet.

Parameters
num_dataThe number of data bytes (0, 1 or 2).
headerSystem common status byte.
data1MIDI data byte 1.
data2MIDI data byte 2.
timestamp13-bit BLE-MIDI timestamp.
Return values
trueSuccessfully added message to the packet.
falseBuffer is too full, send the current packet, reset the packet builder, and try again.

Definition at line 85 of file BLEMIDIPacketBuilder.cpp.

◆ addSysEx()

bool addSysEx ( const uint8_t *&  data,
size_t &  length,
uint16_t  timestamp 
)

Try adding (part of) a SysEx message to the packet.

Parameters
[in,out]dataPointer to the first byte of the SysEx message. At the end, this will point to the first byte to send in the next packet, or nullptr if the message was finished.
[in,out]lengthThe number of bytes in the SysEx message. At the end, this will be set to remaining number of bytes to send in the next packet.
[in]timestamp13-bit BLE-MIDI timestamp.
Return values
trueSuccessfully added (part of) the message to the packet.
falseBuffer is too full, send the current packet, reset the packet builder, and try again.

If the message fits in a single packet, length is set to 0 (no remaining data bytes) and data is set to nullptr.

For example:

BLEMIDIPacketBuilder packetbuilder;
const uint8_t *data = (...);
size_t length = (...);
uint16_t timestamp = (...);
if (!packetbuilder.addSysEx(data, length, timestamp)) {
sendnow(packetbuilder.getBuffer(), packetbuilder.getSize());
packetbuilder.reset();
packetbuilder.addSysEx(data, length, timestamp)
}
while (data) {
sendnow(packetbuilder.getBuffer(), packetbuilder.getSize());
packetbuilder.reset();
packetbuilder.continueSysEx(data, length, timestamp);
}
Class for building MIDI over Bluetooth Low Energy packets.
const uint8_t * getBuffer() const
Get a pointer to the packet data buffer.
uint16_t getSize() const
Get the size of the current packet.
void continueSysEx(const uint8_t *&data, size_t &length, uint16_t timestamp)
Add a SysEx continuation to the packet.
bool addSysEx(const uint8_t *&data, size_t &length, uint16_t timestamp)
Try adding (part of) a SysEx message to the packet.
void reset()
Reset the builder to start a new packet.

Definition at line 105 of file BLEMIDIPacketBuilder.cpp.

◆ continueSysEx()

void continueSysEx ( const uint8_t *&  data,
size_t &  length,
uint16_t  timestamp 
)

Add a SysEx continuation to the packet.

Parameters
[in,out]dataPointer to the first byte of the SysEx message to send in this continuation packet. At the end, this will point to the first byte to send in the next packet, or nullptr if the message was finished.
[in,out]lengthThe number of remaining bytes in the SysEx message. At the end, this will be set to remaining number of bytes to send in the next packet.
[in]timestamp13-bit BLE-MIDI timestamp.

If the message can be completed in a single packet, length is set to 0 (no remaining data bytes) and data is set to nullptr.

See also
addSysEx()

Definition at line 137 of file BLEMIDIPacketBuilder.cpp.

Member Data Documentation

◆ runningHeader

uint8_t runningHeader = 0
private

Definition at line 12 of file BLEMIDIPacketBuilder.hpp.

◆ runningTimestamp

uint8_t runningTimestamp = 0
private

Definition at line 13 of file BLEMIDIPacketBuilder.hpp.

◆ buffer

std::vector<uint8_t> buffer = std::vector<uint8_t>(0)
private

Definition at line 14 of file BLEMIDIPacketBuilder.hpp.

◆ SysExStart

constexpr const uint8_t SysExStart
staticconstexprprivate
Initial value:
=
static_cast<uint8_t>(MIDIMessageType::SYSEX_START)

Definition at line 16 of file BLEMIDIPacketBuilder.hpp.

◆ SysExEnd

constexpr const uint8_t SysExEnd
staticconstexprprivate
Initial value:
=
static_cast<uint8_t>(MIDIMessageType::SYSEX_END)

Definition at line 18 of file BLEMIDIPacketBuilder.hpp.


The documentation for this class was generated from the following files: