ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
midi_parser.h
Go to the documentation of this file.
1#pragma once
2
4
5#include <cstddef>
6#include <cstdint>
7
8namespace esphome::ble_midi {
9
10// Decoded MIDI message types. Status bytes have the high bit set; the low nibble of a channel-voice status byte
11// (0x80-0xEF) is the channel, system messages (0xF0-0xFF) have none.
12enum class MessageType : uint8_t {
13 NOTE_OFF, // 0x80
14 NOTE_ON, // 0x90
15 POLY_AFTERTOUCH, // 0xA0
16 CONTROL_CHANGE, // 0xB0
17 PROGRAM_CHANGE, // 0xC0
18 CHANNEL_AFTERTOUCH, // 0xD0
19 PITCH_BEND, // 0xE0
20 SYSEX, // 0xF0 ... 0xF7, possibly spread over several BLE packets
21 SYSEX_INCOMPLETE, // a SysEx cut short by another status byte or longer than the buffer
22 SYSTEM_COMMON, // 0xF1-0xF6, e.g. quarter frame, song position
23 SYSTEM_REAL_TIME, // 0xF8-0xFF, e.g. clock, start, stop
24 INCOMPLETE, // a channel or system common message cut short by another status byte
25 UNKNOWN, // malformed/undecodable byte
26};
27
28PROGMEM_STRING_TABLE(MessageTypeNames, "NOTE_OFF", "NOTE_ON", "POLY_AFTERTOUCH", "CONTROL_CHANGE", "PROGRAM_CHANGE",
29 "CHANNEL_AFTERTOUCH", "PITCH_BEND", "SYSEX", "SYSEX_INCOMPLETE", "SYSTEM_COMMON",
30 "SYSTEM_REAL_TIME", "INCOMPLETE", "UNKNOWN");
31
35 // Status byte followed by its data bytes; a SysEx includes the 0xF0/0xF7 wrappers
36 const uint8_t *data{nullptr};
37 uint16_t length{0};
39
40 uint8_t status() const { return this->data[0]; }
41 uint8_t channel() const { return this->data[0] & 0x0F; }
42 // The data bytes of a complete channel-voice message: note and velocity, controller and value, or program
43 uint8_t data1() const { return this->data[1]; }
44 uint8_t data2() const { return this->data[2]; }
45 // PITCH_BEND: 14-bit value re-centered on zero (-8192..8191).
46 int16_t pitch_bend() const {
47 return static_cast<int16_t>((static_cast<uint16_t>(this->data[2]) << 7) | this->data[1]) - 8192;
48 }
49};
50
52using MidiMessageHandler = void (*)(void *ctx, const MidiMessage &message);
53
74class MidiParser final {
75 public:
77 MidiParser(uint8_t *sysex_buffer, uint16_t sysex_capacity)
79
80 uint16_t sysex_capacity() const { return this->sysex_capacity_; }
81
84 void reset();
85
88 void feed(const uint8_t *data, size_t length, MidiMessageHandler handler, void *ctx);
89
91 static uint8_t expected_data_bytes(uint8_t status);
92
93 protected:
94 void emit_(MessageType type, const uint8_t *data, uint16_t length, MidiMessageHandler handler, void *ctx) {
95 handler(ctx, MidiMessage{data, length, type});
96 }
97 void emit_current_(MidiMessageHandler handler, void *ctx);
98 void take_data_(const uint8_t *byte, MidiMessageHandler handler, void *ctx);
99 void end_sysex_(bool complete, MidiMessageHandler handler, void *ctx);
100 void sysex_push_(uint8_t byte);
101
102 // SysEx reassembly across packets.
103 uint8_t *const sysex_buffer_;
104 const uint16_t sysex_capacity_;
105 uint16_t sysex_length_{0};
106 bool sysex_active_{false};
107 bool sysex_overflow_{false};
108
109 // Last channel-voice status byte, sticky across bytes and packets until a new
110 // status byte or a system-common message clears it (MIDI running status).
111 uint8_t running_status_{0};
112
113 // Message being assembled: status byte plus up to two data bytes.
114 uint8_t current_message_[3]{};
115 uint8_t current_length_{0};
117};
118
119// A BLE-MIDI packet starts with a header byte and a timestamp byte, both with bit 7 set. The remaining
120// timestamp bits serve jitter reconstruction only and are left at zero when transmitting.
121static constexpr uint8_t PACKET_HEADER = 0x80;
122static constexpr uint8_t PACKET_TIMESTAMP = 0x80;
123static constexpr uint8_t STATUS_SYSEX_START = 0xF0;
124static constexpr uint8_t STATUS_SYSEX_END = 0xF7;
125
129size_t frame_sysex(const uint8_t *payload, size_t length, uint8_t *out, size_t out_size);
130
131} // namespace esphome::ble_midi
Decoder for the BLE-MIDI packet format (Apple/MMA "Bluetooth Low EnergyMIDI" specification,...
Definition midi_parser.h:74
void take_data_(const uint8_t *byte, MidiMessageHandler handler, void *ctx)
uint16_t sysex_capacity() const
Definition midi_parser.h:80
void feed(const uint8_t *data, size_t length, MidiMessageHandler handler, void *ctx)
Feed one BLE notification payload.
void emit_current_(MidiMessageHandler handler, void *ctx)
static uint8_t expected_data_bytes(uint8_t status)
Number of data bytes that follow a status byte other than SysEx.
void emit_(MessageType type, const uint8_t *data, uint16_t length, MidiMessageHandler handler, void *ctx)
Definition midi_parser.h:94
MidiParser(uint8_t *sysex_buffer, uint16_t sysex_capacity)
sysex_buffer reassembles SysEx messages; one longer than sysex_capacity bytes is reported incomplete.
Definition midi_parser.h:77
void sysex_push_(uint8_t byte)
void reset()
Drop all parser state.
void end_sysex_(bool complete, MidiMessageHandler handler, void *ctx)
const LogString * message
Definition component.cpp:35
uint8_t type
std::vector< uint8_t > & out
Definition gif.cpp:49
PROGMEM_STRING_TABLE(MessageTypeNames, "NOTE_OFF", "NOTE_ON", "POLY_AFTERTOUCH", "CONTROL_CHANGE", "PROGRAM_CHANGE", "CHANNEL_AFTERTOUCH", "PITCH_BEND", "SYSEX", "SYSEX_INCOMPLETE", "SYSTEM_COMMON", "SYSTEM_REAL_TIME", "INCOMPLETE", "UNKNOWN")
size_t frame_sysex(const uint8_t *payload, size_t length, uint8_t *out, size_t out_size)
Frame a SysEx payload for one BLE-MIDI packet: 0xF0 and 0xF7 are added when the payload lacks them,...
void(*)(void *ctx, const MidiMessage &message) MidiMessageHandler
Called once per decoded message with the context passed to feed().
Definition midi_parser.h:52
A decoded MIDI message.
Definition midi_parser.h:34
uint16_t length
Definition tt21100.cpp:0