ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
ble_midi.h
Go to the documentation of this file.
1#pragma once
2
6
7#ifdef USE_ESP32
8
11
12#include "midi_parser.h"
13
14#include <esp_gattc_api.h>
15
16#include <cstdint>
17#include <span>
18
19namespace esphome::ble_midi {
20
22
24using ByteSpan = std::span<const uint8_t>;
25
27static constexpr size_t MAX_TX_MIDI_BYTES = 128;
28
36class BLEMidi final : public Component, public ble_client::BLEClientNode {
37 public:
39 BLEMidi(uint8_t *sysex_buffer, uint16_t sysex_capacity, bool pair)
40 : parser_(sysex_buffer, sysex_capacity), pair_(pair) {}
41
42 void dump_config() override;
43 float get_setup_priority() const override { return setup_priority::AFTER_BLUETOOTH; }
44
45 void gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
46 esp_ble_gattc_cb_param_t *param) override;
47
50 bool is_ready() const { return this->notify_registered_; }
51
52 // Channel is 0-15, note/velocity/controller/value/program are 0-127; anything else is refused with a warning.
53 void send_note_on(int32_t note, int32_t velocity, int32_t channel);
54 void send_note_off(int32_t note, int32_t velocity, int32_t channel);
55 void send_control_change(int32_t control_number, int32_t value, int32_t channel);
56 void send_program_change(int32_t program, int32_t channel);
58 void send_pitch_bend(int32_t value, int32_t channel);
61 void send_sysex(const uint8_t *payload, size_t length);
63 void send_raw(const uint8_t *bytes, size_t length);
64
65 template<typename F> void add_on_connect_callback(F &&callback) {
66 this->connect_callback_.add(std::forward<F>(callback));
67 }
68 template<typename F> void add_on_disconnect_callback(F &&callback) {
69 this->disconnect_callback_.add(std::forward<F>(callback));
70 }
72 template<typename F> void add_on_note_on_callback(F &&callback) {
73 this->note_on_callback_.add(std::forward<F>(callback));
74 }
76 template<typename F> void add_on_note_off_callback(F &&callback) {
77 this->note_off_callback_.add(std::forward<F>(callback));
78 }
80 template<typename F> void add_on_control_change_callback(F &&callback) {
81 this->control_change_callback_.add(std::forward<F>(callback));
82 }
84 template<typename F> void add_on_program_change_callback(F &&callback) {
85 this->program_change_callback_.add(std::forward<F>(callback));
86 }
88 template<typename F> void add_on_pitch_bend_callback(F &&callback) {
89 this->pitch_bend_callback_.add(std::forward<F>(callback));
90 }
92 template<typename F> void add_on_sysex_callback(F &&callback) {
93 this->sysex_callback_.add(std::forward<F>(callback));
94 }
96 template<typename F> void add_on_message_callback(F &&callback) {
97 this->message_callback_.add(std::forward<F>(callback));
98 }
99
100 protected:
101 static void dispatch_message(void *ctx, const MidiMessage &message) {
102 static_cast<BLEMidi *>(ctx)->handle_message_(message);
103 }
106 bool write_midi_(const uint8_t *midi_bytes, size_t length);
108 bool write_packet_(uint8_t *packet, size_t midi_length);
110 void send_channel_(uint8_t status, int32_t channel, int32_t data1, int32_t data2, size_t length);
112 void fail_session_();
113
117 LazyCallbackManager<void(uint8_t, uint8_t, uint8_t)> note_on_callback_;
118 LazyCallbackManager<void(uint8_t, uint8_t, uint8_t)> note_off_callback_;
119 LazyCallbackManager<void(uint8_t, uint8_t, uint8_t)> control_change_callback_;
125 // Notification descriptor of the MIDI characteristic; the link is ready once the device accepts the write to it
126 uint16_t cccd_handle_{0};
127 // The ATT MTU the link negotiated; every packet has to fit it
128 uint16_t mtu_{23};
130 // Write without response has lower latency and is preferred when the
131 // characteristic supports it.
133 const bool pair_;
134};
135
136} // namespace esphome::ble_midi
137
138#endif // USE_ESP32
Client for devices implementing the standard BLE-MIDI service, e.g.
Definition ble_midi.h:36
BLEMidi(uint8_t *sysex_buffer, uint16_t sysex_capacity, bool pair)
sysex_buffer holds sysex_capacity bytes; longer SysEx messages are truncated.
Definition ble_midi.h:39
void send_control_change(int32_t control_number, int32_t value, int32_t channel)
Definition ble_midi.cpp:265
void send_program_change(int32_t program, int32_t channel)
Definition ble_midi.cpp:269
LazyCallbackManager< void(uint8_t, uint8_t, uint8_t)> note_on_callback_
Definition ble_midi.h:117
float get_setup_priority() const override
Definition ble_midi.h:43
LazyCallbackManager< void(uint8_t, uint8_t, uint8_t)> control_change_callback_
Definition ble_midi.h:119
LazyCallbackManager< void(uint8_t, uint8_t, uint8_t)> note_off_callback_
Definition ble_midi.h:118
LazyCallbackManager< void()> disconnect_callback_
Definition ble_midi.h:116
void send_note_off(int32_t note, int32_t velocity, int32_t channel)
Definition ble_midi.cpp:261
void send_channel_(uint8_t status, int32_t channel, int32_t data1, int32_t data2, size_t length)
Channel-voice message: the status byte takes the channel; out-of-range values are refused.
Definition ble_midi.cpp:243
LazyCallbackManager< void(int16_t, uint8_t)> pitch_bend_callback_
Definition ble_midi.h:121
void send_raw(const uint8_t *bytes, size_t length)
Send raw MIDI bytes (status byte followed by its data bytes).
Definition ble_midi.cpp:293
void add_on_pitch_bend_callback(F &&callback)
(value, channel), value being -8192 to 8191
Definition ble_midi.h:88
void dump_config() override
Definition ble_midi.cpp:29
void add_on_program_change_callback(F &&callback)
(program, channel)
Definition ble_midi.h:84
bool write_packet_(uint8_t *packet, size_t midi_length)
Write a packet whose MIDI bytes already sit at packet + 2; the header and timestamp are filled in.
Definition ble_midi.cpp:204
void send_note_on(int32_t note, int32_t velocity, int32_t channel)
Definition ble_midi.cpp:257
void add_on_note_on_callback(F &&callback)
(note, velocity, channel)
Definition ble_midi.h:72
void gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if, esp_ble_gattc_cb_param_t *param) override
Definition ble_midi.cpp:38
void send_sysex(const uint8_t *payload, size_t length)
Send a System Exclusive message.
Definition ble_midi.cpp:282
void send_pitch_bend(int32_t value, int32_t channel)
Pitch bend value is -8192 to 8191, centered on zero.
Definition ble_midi.cpp:273
void fail_session_()
Set a warning and drop the link so that ble_client reconnects and the setup runs again.
Definition ble_midi.cpp:151
void add_on_connect_callback(F &&callback)
Definition ble_midi.h:65
void add_on_disconnect_callback(F &&callback)
Definition ble_midi.h:68
LazyCallbackManager< void(ByteSpan)> message_callback_
Definition ble_midi.h:123
LazyCallbackManager< void(ByteSpan)> sysex_callback_
Definition ble_midi.h:122
LazyCallbackManager< void(uint8_t, uint8_t)> program_change_callback_
Definition ble_midi.h:120
void add_on_message_callback(F &&callback)
The raw bytes of every decoded message.
Definition ble_midi.h:96
void add_on_control_change_callback(F &&callback)
(control_number, value, channel)
Definition ble_midi.h:80
bool is_ready() const
True once the MIDI characteristic has been discovered and notifications are enabled.
Definition ble_midi.h:50
static void dispatch_message(void *ctx, const MidiMessage &message)
Definition ble_midi.h:101
void add_on_sysex_callback(F &&callback)
The SysEx payload without the 0xF0/0xF7 wrappers.
Definition ble_midi.h:92
void handle_message_(const MidiMessage &message)
Definition ble_midi.cpp:157
void add_on_note_off_callback(F &&callback)
(note, velocity, channel); a Note On with velocity zero is reported here as well
Definition ble_midi.h:76
bool write_midi_(const uint8_t *midi_bytes, size_t length)
Wrap MIDI bytes in a BLE-MIDI packet and write them to the MIDI characteristic.
Definition ble_midi.cpp:232
LazyCallbackManager< void()> connect_callback_
Definition ble_midi.h:115
Decoder for the BLE-MIDI packet format (Apple/MMA "Bluetooth Low EnergyMIDI" specification,...
Definition midi_parser.h:74
const LogString * message
Definition component.cpp:35
std::span< const uint8_t > ByteSpan
The bytes of a received message, valid for the duration of the automation.
Definition ble_midi.h:24
constexpr float AFTER_BLUETOOTH
Definition component.h:49
uint32_t value
Definition hal.cpp:41
A decoded MIDI message.
Definition midi_parser.h:34