ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
esphome::ble_midi::BLEMidi Class Referencefinal

Client for devices implementing the standard BLE-MIDI service, e.g. More...

#include <ble_midi.h>

Inheritance diagram for esphome::ble_midi::BLEMidi:
esphome::Component esphome::ble_client::BLEClientNode

Public Member Functions

 BLEMidi (uint8_t *sysex_buffer, uint16_t sysex_capacity, bool pair)
 sysex_buffer holds sysex_capacity bytes; longer SysEx messages are truncated.
 
void dump_config () override
 
float get_setup_priority () const override
 
void gattc_event_handler (esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if, esp_ble_gattc_cb_param_t *param) override
 
bool is_ready () const
 True once the MIDI characteristic has been discovered and notifications are enabled.
 
void send_note_on (int32_t note, int32_t velocity, int32_t channel)
 
void send_note_off (int32_t note, int32_t velocity, int32_t channel)
 
void send_control_change (int32_t control_number, int32_t value, int32_t channel)
 
void send_program_change (int32_t program, int32_t channel)
 
void send_pitch_bend (int32_t value, int32_t channel)
 Pitch bend value is -8192 to 8191, centered on zero.
 
void send_sysex (const uint8_t *payload, size_t length)
 Send a System Exclusive message.
 
void send_raw (const uint8_t *bytes, size_t length)
 Send raw MIDI bytes (status byte followed by its data bytes).
 
template<typename F >
void add_on_connect_callback (F &&callback)
 
template<typename F >
void add_on_disconnect_callback (F &&callback)
 
template<typename F >
void add_on_note_on_callback (F &&callback)
 (note, velocity, channel)
 
template<typename F >
void add_on_note_off_callback (F &&callback)
 (note, velocity, channel); a Note On with velocity zero is reported here as well
 
template<typename F >
void add_on_control_change_callback (F &&callback)
 (control_number, value, channel)
 
template<typename F >
void add_on_program_change_callback (F &&callback)
 (program, channel)
 
template<typename F >
void add_on_pitch_bend_callback (F &&callback)
 (value, channel), value being -8192 to 8191
 
template<typename F >
void add_on_sysex_callback (F &&callback)
 The SysEx payload without the 0xF0/0xF7 wrappers.
 
template<typename F >
void add_on_message_callback (F &&callback)
 The raw bytes of every decoded message.
 
- Public Member Functions inherited from esphome::Component
virtual void setup ()
 Where the component's initialization should happen.
 
virtual void loop ()
 This method will be called repeatedly.
 
float get_actual_setup_priority () const
 
void set_setup_priority (float priority)
 
void call ()
 
virtual void on_shutdown ()
 
virtual void on_safe_shutdown ()
 
virtual bool teardown ()
 Called during teardown to allow component to gracefully finish operations.
 
virtual void on_powerdown ()
 Called last before a reboot or deep sleep to power down hardware.
 
uint8_t get_component_state () const
 
void reset_to_construction_state ()
 Reset this component back to the construction state to allow setup to run again.
 
bool is_in_loop_state () const
 Check if this component has completed setup and is in the loop state.
 
bool is_idle () const
 Check if this component is idle.
 
void mark_failed ()
 Mark this component as failed.
 
void mark_failed (const LogString *message)
 
bool ESPHOME_ALWAYS_INLINE setup_check (bool ok)
 Marks the component failed with message (default "Communication failed") unless ok; returns ok.
 
bool ESPHOME_ALWAYS_INLINE setup_check (bool ok, const LogString *message)
 
void disable_loop ()
 Disable this component's loop.
 
void enable_loop ()
 Enable this component's loop.
 
void enable_loop_soon_any_context ()
 Thread and ISR-safe version of enable_loop() that can be called from any context.
 
bool is_failed () const
 
bool is_ready () const
 
virtual bool can_proceed ()
 
bool status_has_warning () const
 
bool status_has_error () const
 
void status_set_warning ()
 
void status_set_warning (const char *message)
 
void status_set_warning (const LogString *message)
 
bool status_comm_result (bool ok)
 Clears the warning when ok, else sets it with message (default "Communication failed"); returns ok.
 
bool status_comm_result (bool ok, const LogString *message)
 
void status_set_error ()
 
void status_set_error (const LogString *message)
 
void status_clear_warning ()
 
void status_clear_error ()
 
 ESPDEPRECATED ("Use status_momentary_warning() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_warning(const char *name
 
void status_momentary_warning (uint32_t length=5000)
 Set warning status flag and clear it after length ms.
 
void status_momentary_warning (const LogString *message, uint32_t length=5000)
 
 ESPDEPRECATED ("Use status_momentary_error() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_error(const char *name
 
void status_momentary_error (uint32_t length=5000)
 Set error status flag and clear it after length ms.
 
void status_momentary_error (const LogString *message, uint32_t length=5000)
 
bool has_overridden_loop () const
 
const LogString * get_component_log_str () const ESPHOME_ALWAYS_INLINE
 Get the integration where this component was declared as a LogString for logging.
 
bool should_warn_of_blocking (uint32_t blocking_time, uint32_t &threshold_ms_out)
 
- Public Member Functions inherited from esphome::ble_client::BLEClientNode
virtual void gap_event_handler (esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param)
 
virtual void loop ()
 
void set_address (uint64_t address)
 
BLEClient * parent ()
 
void set_ble_client_parent (BLEClient *parent)
 

Protected Member Functions

void handle_message_ (const MidiMessage &message)
 
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.
 
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.
 
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.
 
void fail_session_ ()
 Set a warning and drop the link so that ble_client reconnects and the setup runs again.
 
- Protected Member Functions inherited from esphome::Component
friend void::setup ()
 
friend void::original_setup ()
 
void set_component_source_ (uint8_t index)
 Set where this component was loaded from for some debug messages.
 
virtual void call_setup ()
 
void call_dump_config_ ()
 
void enable_loop_slow_path_ ()
 
void set_component_state_ (uint8_t state)
 Helper to set component state (clears state bits and sets new state)
 
bool set_status_flag_ (uint8_t flag)
 Helper to set a status LED flag on both this component and the app.
 
bool set_error_flag_ (const LogString *message)
 Set the error flag and log it; true when it was not set before.
 
void set_interval (const char *name, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a const char* name.
 
void set_interval (uint32_t id, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a numeric ID (zero heap allocation).
 
void set_interval (InternalSchedulerID id, uint32_t interval, std::function< void()> &&f)
 
void set_interval (uint32_t interval, std::function< void()> &&f)
 
bool cancel_interval (const char *name)
 Cancel an interval function.
 
bool cancel_interval (uint32_t id)
 
bool cancel_interval (InternalSchedulerID id)
 
void set_timeout (const char *name, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a const char* name.
 
void set_timeout (uint32_t id, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a numeric ID (zero heap allocation).
 
void set_timeout (InternalSchedulerID id, uint32_t timeout, std::function< void()> &&f)
 
void set_timeout (uint32_t timeout, std::function< void()> &&f)
 
bool cancel_timeout (const char *name)
 Cancel a timeout function.
 
bool cancel_timeout (uint32_t id)
 
bool cancel_timeout (InternalSchedulerID id)
 
void defer (const char *name, std::function< void()> &&f)
 Defer a callback to the next loop() call with a const char* name.
 
void defer (std::function< void()> &&f)
 Defer a callback to the next loop() call.
 
void defer (uint32_t id, std::function< void()> &&f)
 Defer a callback with a numeric ID (zero heap allocation)
 
bool cancel_defer (const char *name)
 Cancel a defer callback using the specified name, name must not be empty.
 
bool cancel_defer (uint32_t id)
 
void status_clear_warning_slow_path_ ()
 
void status_clear_error_slow_path_ ()
 

Static Protected Member Functions

static void dispatch_message (void *ctx, const MidiMessage &message)
 

Protected Attributes

MidiParser parser_
 
LazyCallbackManager< void()> connect_callback_
 
LazyCallbackManager< void()> disconnect_callback_
 
LazyCallbackManager< void(uint8_t, uint8_t, uint8_t)> note_on_callback_
 
LazyCallbackManager< void(uint8_t, uint8_t, uint8_t)> note_off_callback_
 
LazyCallbackManager< void(uint8_t, uint8_t, uint8_t)> control_change_callback_
 
LazyCallbackManager< void(uint8_t, uint8_t)> program_change_callback_
 
LazyCallbackManager< void(int16_t, uint8_t)> pitch_bend_callback_
 
LazyCallbackManager< void(ByteSpan)> sysex_callback_
 
LazyCallbackManager< void(ByteSpan)> message_callback_
 
uint16_t characteristic_handle_ {0}
 
uint16_t cccd_handle_ {0}
 
uint16_t mtu_ {23}
 
bool notify_registered_ {false}
 
bool write_without_response_ {false}
 
const bool pair_
 
- Protected Attributes inherited from esphome::Component
uint8_t component_source_index_ {0}
 Index into component source PROGMEM lookup table (0 = not set)
 
uint8_t warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_CS}
 Warn threshold in centiseconds (max 2550ms)
 
uint8_t component_state_ {0x00}
 State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bit 5: Has overridden loop() (set at registration time) Bits 6-7: Unused - reserved for future expansion.
 
volatile bool pending_enable_loop_ {false}
 ISR-safe flag for enable_loop_soon_any_context.
 
ComponentRuntimeStats runtime_stats_
 
- Protected Attributes inherited from esphome::ble_client::BLEClientNode
BLEClient * parent_
 
uint64_t address_
 

Additional Inherited Members

- Data Fields inherited from esphome::Component
uint32_t length = 5000)
 
- Data Fields inherited from esphome::ble_client::BLEClientNode
espbt::ESPBTClient * client
 
espbt::ClientState node_state
 

Detailed Description

Client for devices implementing the standard BLE-MIDI service, e.g.

wireless MIDI keyboards and pad controllers. Incoming messages are exposed as automation triggers; outgoing messages are sent with the ble_midi.send_* actions.

Specification: "Specification for MIDI over Bluetooth Low Energy (BLE-MIDI)", MIDI Association, document M1-2017-11-01.

Definition at line 36 of file ble_midi.h.

Constructor & Destructor Documentation

◆ BLEMidi()

esphome::ble_midi::BLEMidi::BLEMidi ( uint8_t * sysex_buffer,
uint16_t sysex_capacity,
bool pair )
inline

sysex_buffer holds sysex_capacity bytes; longer SysEx messages are truncated.

Definition at line 39 of file ble_midi.h.

Member Function Documentation

◆ add_on_connect_callback()

template<typename F >
void esphome::ble_midi::BLEMidi::add_on_connect_callback ( F && callback)
inline

Definition at line 65 of file ble_midi.h.

◆ add_on_control_change_callback()

template<typename F >
void esphome::ble_midi::BLEMidi::add_on_control_change_callback ( F && callback)
inline

(control_number, value, channel)

Definition at line 80 of file ble_midi.h.

◆ add_on_disconnect_callback()

template<typename F >
void esphome::ble_midi::BLEMidi::add_on_disconnect_callback ( F && callback)
inline

Definition at line 68 of file ble_midi.h.

◆ add_on_message_callback()

template<typename F >
void esphome::ble_midi::BLEMidi::add_on_message_callback ( F && callback)
inline

The raw bytes of every decoded message.

Definition at line 96 of file ble_midi.h.

◆ add_on_note_off_callback()

template<typename F >
void esphome::ble_midi::BLEMidi::add_on_note_off_callback ( F && callback)
inline

(note, velocity, channel); a Note On with velocity zero is reported here as well

Definition at line 76 of file ble_midi.h.

◆ add_on_note_on_callback()

template<typename F >
void esphome::ble_midi::BLEMidi::add_on_note_on_callback ( F && callback)
inline

(note, velocity, channel)

Definition at line 72 of file ble_midi.h.

◆ add_on_pitch_bend_callback()

template<typename F >
void esphome::ble_midi::BLEMidi::add_on_pitch_bend_callback ( F && callback)
inline

(value, channel), value being -8192 to 8191

Definition at line 88 of file ble_midi.h.

◆ add_on_program_change_callback()

template<typename F >
void esphome::ble_midi::BLEMidi::add_on_program_change_callback ( F && callback)
inline

(program, channel)

Definition at line 84 of file ble_midi.h.

◆ add_on_sysex_callback()

template<typename F >
void esphome::ble_midi::BLEMidi::add_on_sysex_callback ( F && callback)
inline

The SysEx payload without the 0xF0/0xF7 wrappers.

Definition at line 92 of file ble_midi.h.

◆ dispatch_message()

static void esphome::ble_midi::BLEMidi::dispatch_message ( void * ctx,
const MidiMessage & message )
inlinestaticprotected

Definition at line 101 of file ble_midi.h.

◆ dump_config()

void esphome::ble_midi::BLEMidi::dump_config ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 29 of file ble_midi.cpp.

◆ fail_session_()

void esphome::ble_midi::BLEMidi::fail_session_ ( )
protected

Set a warning and drop the link so that ble_client reconnects and the setup runs again.

Definition at line 151 of file ble_midi.cpp.

◆ gattc_event_handler()

void esphome::ble_midi::BLEMidi::gattc_event_handler ( esp_gattc_cb_event_t event,
esp_gatt_if_t gattc_if,
esp_ble_gattc_cb_param_t * param )
overridevirtual

Reimplemented from esphome::ble_client::BLEClientNode.

Definition at line 38 of file ble_midi.cpp.

◆ get_setup_priority()

float esphome::ble_midi::BLEMidi::get_setup_priority ( ) const
inlineoverridevirtual

Reimplemented from esphome::Component.

Definition at line 43 of file ble_midi.h.

◆ handle_message_()

void esphome::ble_midi::BLEMidi::handle_message_ ( const MidiMessage & message)
protected

Definition at line 157 of file ble_midi.cpp.

◆ is_ready()

bool esphome::ble_midi::BLEMidi::is_ready ( ) const
inline

True once the MIDI characteristic has been discovered and notifications are enabled.

Definition at line 50 of file ble_midi.h.

◆ send_channel_()

void esphome::ble_midi::BLEMidi::send_channel_ ( uint8_t status,
int32_t channel,
int32_t data1,
int32_t data2,
size_t length )
protected

Channel-voice message: the status byte takes the channel; out-of-range values are refused.

Definition at line 243 of file ble_midi.cpp.

◆ send_control_change()

void esphome::ble_midi::BLEMidi::send_control_change ( int32_t control_number,
int32_t value,
int32_t channel )

Definition at line 265 of file ble_midi.cpp.

◆ send_note_off()

void esphome::ble_midi::BLEMidi::send_note_off ( int32_t note,
int32_t velocity,
int32_t channel )

Definition at line 261 of file ble_midi.cpp.

◆ send_note_on()

void esphome::ble_midi::BLEMidi::send_note_on ( int32_t note,
int32_t velocity,
int32_t channel )

Definition at line 257 of file ble_midi.cpp.

◆ send_pitch_bend()

void esphome::ble_midi::BLEMidi::send_pitch_bend ( int32_t value,
int32_t channel )

Pitch bend value is -8192 to 8191, centered on zero.

Definition at line 273 of file ble_midi.cpp.

◆ send_program_change()

void esphome::ble_midi::BLEMidi::send_program_change ( int32_t program,
int32_t channel )

Definition at line 269 of file ble_midi.cpp.

◆ send_raw()

void esphome::ble_midi::BLEMidi::send_raw ( const uint8_t * bytes,
size_t length )

Send raw MIDI bytes (status byte followed by its data bytes).

Definition at line 293 of file ble_midi.cpp.

◆ send_sysex()

void esphome::ble_midi::BLEMidi::send_sysex ( const uint8_t * payload,
size_t length )

Send a System Exclusive message.

The 0xF0/0xF7 wrappers are added if the payload does not already carry them.

Definition at line 282 of file ble_midi.cpp.

◆ write_midi_()

bool esphome::ble_midi::BLEMidi::write_midi_ ( const uint8_t * midi_bytes,
size_t length )
protected

Wrap MIDI bytes in a BLE-MIDI packet and write them to the MIDI characteristic.

Definition at line 232 of file ble_midi.cpp.

◆ write_packet_()

bool esphome::ble_midi::BLEMidi::write_packet_ ( uint8_t * packet,
size_t midi_length )
protected

Write a packet whose MIDI bytes already sit at packet + 2; the header and timestamp are filled in.

Definition at line 204 of file ble_midi.cpp.

Field Documentation

◆ cccd_handle_

uint16_t esphome::ble_midi::BLEMidi::cccd_handle_ {0}
protected

Definition at line 126 of file ble_midi.h.

◆ characteristic_handle_

uint16_t esphome::ble_midi::BLEMidi::characteristic_handle_ {0}
protected

Definition at line 124 of file ble_midi.h.

◆ connect_callback_

LazyCallbackManager<void()> esphome::ble_midi::BLEMidi::connect_callback_
protected

Definition at line 115 of file ble_midi.h.

◆ control_change_callback_

LazyCallbackManager<void(uint8_t, uint8_t, uint8_t)> esphome::ble_midi::BLEMidi::control_change_callback_
protected

Definition at line 119 of file ble_midi.h.

◆ disconnect_callback_

LazyCallbackManager<void()> esphome::ble_midi::BLEMidi::disconnect_callback_
protected

Definition at line 116 of file ble_midi.h.

◆ message_callback_

LazyCallbackManager<void(ByteSpan)> esphome::ble_midi::BLEMidi::message_callback_
protected

Definition at line 123 of file ble_midi.h.

◆ mtu_

uint16_t esphome::ble_midi::BLEMidi::mtu_ {23}
protected

Definition at line 128 of file ble_midi.h.

◆ note_off_callback_

LazyCallbackManager<void(uint8_t, uint8_t, uint8_t)> esphome::ble_midi::BLEMidi::note_off_callback_
protected

Definition at line 118 of file ble_midi.h.

◆ note_on_callback_

LazyCallbackManager<void(uint8_t, uint8_t, uint8_t)> esphome::ble_midi::BLEMidi::note_on_callback_
protected

Definition at line 117 of file ble_midi.h.

◆ notify_registered_

bool esphome::ble_midi::BLEMidi::notify_registered_ {false}
protected

Definition at line 129 of file ble_midi.h.

◆ pair_

const bool esphome::ble_midi::BLEMidi::pair_
protected

Definition at line 133 of file ble_midi.h.

◆ parser_

MidiParser esphome::ble_midi::BLEMidi::parser_
protected

Definition at line 114 of file ble_midi.h.

◆ pitch_bend_callback_

LazyCallbackManager<void(int16_t, uint8_t)> esphome::ble_midi::BLEMidi::pitch_bend_callback_
protected

Definition at line 121 of file ble_midi.h.

◆ program_change_callback_

LazyCallbackManager<void(uint8_t, uint8_t)> esphome::ble_midi::BLEMidi::program_change_callback_
protected

Definition at line 120 of file ble_midi.h.

◆ sysex_callback_

LazyCallbackManager<void(ByteSpan)> esphome::ble_midi::BLEMidi::sysex_callback_
protected

Definition at line 122 of file ble_midi.h.

◆ write_without_response_

bool esphome::ble_midi::BLEMidi::write_without_response_ {false}
protected

Definition at line 132 of file ble_midi.h.


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