https://github.com/sauloverissimo/esp32_host_midi
This project provides a complete solution for receiving, interpreting, and displaying MIDI messages via USB and BLE on the ESP32 (especially ESP32-S3) with the T-Display S3.
https://github.com/sauloverissimo/esp32_host_midi
ble esp32 esp32-arduino host lilygo-tdisplay-s3 lovyangfx midi otg pcm5102a st7789 t-display t-display-s3 usb
Last synced: 4 months ago
JSON representation
This project provides a complete solution for receiving, interpreting, and displaying MIDI messages via USB and BLE on the ESP32 (especially ESP32-S3) with the T-Display S3.
- Host: GitHub
- URL: https://github.com/sauloverissimo/esp32_host_midi
- Owner: sauloverissimo
- License: other
- Created: 2025-02-07T13:52:17.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-02-14T19:11:08.000Z (4 months ago)
- Last Synced: 2025-02-14T20:20:46.529Z (4 months ago)
- Topics: ble, esp32, esp32-arduino, host, lilygo-tdisplay-s3, lovyangfx, midi, otg, pcm5102a, st7789, t-display, t-display-s3, usb
- Language: C++
- Homepage: https://github.com/sauloverissimo/ESP32_Host_MIDI
- Size: 283 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ESP32_Host_MIDI 🎹📡
Project developed for ARDUINO IDE:
This project provides a complete solution for receiving, interpreting, and displaying MIDI messages via USB and BLE on the ESP32 (especially ESP32-S3) with the T-Display S3.
---
## English 🇺🇸 🏈
### Overview
The **ESP32_Host_MIDI** library allows the ESP32 to act as a USB host for MIDI devices, interpret incoming data (using functions from the **MIDI_Handler** module), and display this information on the T-Display S3 using **DisplayHandler**. Additionally, the library supports **BLE MIDI** communication, enabling the ESP32 to function as a **BLE MIDI server**.
The library is modular, making it easy to adapt to other hardware by adjusting the configuration files.
### File Structure
- **ESP32_Host_MIDI_Config.h**
Defines the pins used for USB communication and the display.
- *Example:* `USB_DP_PIN`, `USB_DN_PIN`, `TFT_CS_PIN`, `TFT_DC_PIN`, `TFT_RST_PIN`, `TFT_BL_PIN`.
- **ESP32_Host_MIDI.h / ESP32_Host_MIDI.cpp**
Manages USB MIDI communication.
- **Key Functions:**
- `begin()`: Initializes the USB Host and registers the client.
- `task()`: Processes USB events and submits transfers.
- `onMidiMessage(const uint8_t *data, size_t length)`: Virtual function called when a MIDI message is received. Should be overridden to process the message (e.g., using **MIDI_Handler**).
- **ESP32_BLE.h / ESP32_BLE.cpp**
Implements the **BLE MIDI server**, allowing the ESP32 to receive MIDI messages via Bluetooth Low Energy (BLE).
- **Key Functions:**
- `begin()`: Initializes the BLE server and advertises the MIDI service.
- `task()`: Periodically processes BLE events.
- `setMidiMessageCallback()`: Sets a callback to process received BLE MIDI messages.
- `sendMidiMessage()`: Sends MIDI messages via BLE to connected devices.
- **MIDI_Handler.h / MIDI_Handler.cpp**
Provides static functions that interpret raw MIDI data (after removing the USB header) into various formats:
- **Raw Format:** Ex.: `[0x09, 0x90, 0x3C, 0x64]`
- **Short Format:** Ex.: `"90 3C 64"`
- **Note Number:** Ex.: `"60"`
- **Message Type:** Ex.: `"NoteOn"`, `"NoteOff"`, `"Control Change"`, `"Program Change"`, etc.
- **Status:** Ex.: `"9n"`
- **Note Sound with Octave:** Ex.: `"C5"`
- **Message Vector:** A structure that aggregates the interpreted fields.
- **displayhandler.h / displayhandler.cpp**
Manages the display output on the T-Display S3 using the LovyanGFX library.
- **Key Functions:**
- `init()`: Initializes the display, sets rotation (180°), dimensions (320x170), and font size.
- `printMidiMessage(const char* message)`: Displays the formatted message across 5 lines, with the last line ("Octave") highlighted (separator line, larger font, and different color).
- `clear()`: Clears the display.
- **ESP32_Host_MIDI.ino**
Example implementation for the T-Display S3. Integrates USB MIDI reception, BLE MIDI reception, data interpretation (via **MIDI_Handler**), and information display.
- Uses a derived class that overrides `onMidiMessage()` to:
- Remove the USB header from the data.
- Format the data into 5 lines (Raw, Short, Note#, Msg, and Octave).
- Display the message and clear the screen after 1 second.
### Example with Lilygo T-Display S3
The project includes examples in the `examples/T-Display-S3/` folder, with code specifically for this board.
Additionally, the `examples/T-Display-S3/images/` folder contains illustrative images of the project's functionality:
### Operation
1. **MIDI USB-OTG Reception on ESP32:**
When a MIDI device is connected via USB, the ESP32 captures the MIDI data.
2. **MIDI BLE Reception:**
The ESP32 captures MIDI data received via Bluetooth Low Energy (BLE) and processes it in the BLE MIDI server.
3. **Interpretation:**
The virtual function `onMidiMessage()` is called. A derived class removes the header (first byte) and uses **MIDI_Handler** to convert the bytes into readable formats.
4. **Display Output:**
The **DisplayHandler** displays the formatted data across 5 lines (highlighting the last line) on the T-Display S3, which is rotated 180° for correct orientation.
---
# ESP32_Host_MIDI 🎹📡
Projeto desenvolvido para ARDUINO IDE:
Este projeto oferece uma solução completa para receber, interpretar e exibir mensagens MIDI via USB e BLE no ESP32 (especialmente ESP32-S3) com o T‑Display S3.
---
## Português 🇧🇷 ⚽
### Visão Geral
A biblioteca **ESP32_Host_MIDI** permite que o ESP32 atue como host USB para dispositivos MIDI, interprete os dados recebidos (utilizando funções do módulo **MIDI_Handler**) e exiba essas informações no T‑Display S3 através do **DisplayHandler**. Além disso, a biblioteca oferece suporte a comunicação **BLE MIDI**, permitindo que o ESP32 atue como um **servidor MIDI BLE**.
A biblioteca é modular, facilitando adaptações para outros hardwares, bastando ajustar os arquivos de configuração.
### Estrutura dos Arquivos
- **ESP32_Host_MIDI_Config.h**
Define os pinos usados para comunicação USB e para o display.
- *Exemplo:* `USB_DP_PIN`, `USB_DN_PIN`, `TFT_CS_PIN`, `TFT_DC_PIN`, `TFT_RST_PIN`, `TFT_BL_PIN`.
- **ESP32_Host_MIDI.h / ESP32_Host_MIDI.cpp**
Gerencia a comunicação USB MIDI.
- **Funções Principais:**
- `begin()`: Inicializa o USB Host e registra o cliente.
- `task()`: Processa os eventos USB e submete as transferências.
- `onMidiMessage(const uint8_t *data, size_t length)`: Função virtual chamada quando uma mensagem MIDI é recebida. Deve ser sobrescrita para tratar a mensagem (por exemplo, utilizando o **MIDI_Handler**).
- **ESP32_BLE.h / ESP32_BLE.cpp**
Implementa o **servidor MIDI BLE**, permitindo que o ESP32 receba mensagens MIDI via Bluetooth Low Energy (BLE).
- **Funções Principais:**
- `begin()`: Inicializa o servidor BLE e anuncia o serviço MIDI.
- `task()`: Processa eventos BLE periodicamente.
- `setMidiMessageCallback()`: Define um callback para tratar mensagens MIDI recebidas via BLE.
- `sendMidiMessage()`: Envia mensagens MIDI via BLE para dispositivos conectados.
- **MIDI_Handler.h / MIDI_Handler.cpp**
Fornece funções estáticas que interpretam os dados MIDI brutos (após remover o cabeçalho USB) em diversos formatos:
- **Raw Format:** Ex.: `[0x09, 0x90, 0x3C, 0x64]`
- **Short Format:** Ex.: `"90 3C 64"`
- **Note Number:** Ex.: `"60"`
- **Tipo de Mensagem:** Ex.: `"NoteOn"`, `"NoteOff"`, `"Control Change"`, `"Program Change"`, etc.
- **Status:** Ex.: `"9n"`
- **Note Sound com Octave:** Ex.: `"C5"`
- **Message Vector:** Estrutura que reúne os campos interpretados.
- **displayhandler.h / displayhandler.cpp**
Gerencia a exibição das informações no T‑Display S3 utilizando a biblioteca LovyanGFX.
- **Funções Principais:**
- `init()`: Inicializa o display, configura a rotação (180°), dimensões (320x170) e tamanho da fonte.
- `printMidiMessage(const char* message)`: Exibe a mensagem formatada em 5 linhas, com a última ("Octave") destacada (linha separadora, fonte maior e cor diferenciada).
- `clear()`: Limpa o display.
- **ESP32_Host_MIDI.ino**
Exemplo de implementação no T‑Display S3. Integra a recepção USB MIDI, a recepção BLE MIDI, a interpretação dos dados (via **MIDI_Handler**) e a exibição das informações no display.
- Utiliza uma classe derivada que sobrescreve `onMidiMessage()` para:
- Remover o cabeçalho USB dos dados.
- Formatar os dados em 5 linhas (Raw, Short, Note#, Msg e Octave).
- Exibir a mensagem e limpar o display após 1 segundo.
### Exemplo com Lilygo T-Display S3
O projeto inclui exemplos na pasta `examples/T-Display-S3/`, com código específico para essa placa.
Além disso, a pasta `examples/T-Display-S3/images/` contém imagens ilustrativas do funcionamento do projeto:
### Funcionamento
1. **Recepção MIDI USB-OTG ESP32:**
Ao conectar um dispositivo MIDI via USB, o ESP32 captura os dados MIDI.
2. **Recepção MIDI BLE:**
O ESP32 captura os dados MIDI recebidos via Bluetooth Low Energy (BLE) e os trata no servidor MIDI BLE.
3. **Interpretação:**
A função virtual `onMidiMessage()` é chamada. Uma classe derivada remove o cabeçalho (primeiro byte) e utiliza o **MIDI_Handler** para converter os bytes em formatos legíveis.
4. **Exibição:**
O **DisplayHandler** exibe os dados formatados em 5 linhas (com destaque na última linha) no T‑Display S3, que está rotacionado 180° para a orientação correta.
---
# ESP32_Host_MIDI 🎹📡
Proyecto desarrollado para ARDUINO IDE:
Este proyecto proporciona una solución completa para recibir, interpretar y mostrar mensajes MIDI a través de USB y BLE en el ESP32 (especialmente ESP32-S3) con el T-Display S3.
---
## Español 🇪🇸 🐂
### Descripción General
La biblioteca **ESP32_Host_MIDI** permite que el ESP32 actúe como un host USB para dispositivos MIDI, interprete los datos entrantes (utilizando funciones del módulo **MIDI_Handler**) y muestre esta información en el T-Display S3 mediante **DisplayHandler**. Además, la biblioteca es compatible con la comunicación **BLE MIDI**, permitiendo que el ESP32 funcione como un **servidor MIDI BLE**.
La biblioteca es modular, lo que facilita la adaptación a otro hardware mediante la configuración de archivos.
### Estructura de Archivos
- **ESP32_Host_MIDI_Config.h**
Define los pines utilizados para la comunicación USB y la pantalla.
- *Ejemplo:* `USB_DP_PIN`, `USB_DN_PIN`, `TFT_CS_PIN`, `TFT_DC_PIN`, `TFT_RST_PIN`, `TFT_BL_PIN`.
- **ESP32_Host_MIDI.h / ESP32_Host_MIDI.cpp**
Gestiona la comunicación MIDI por USB.
- **Funciones Clave:**
- `begin()`: Inicializa el host USB y registra el cliente.
- `task()`: Procesa eventos USB y envía transferencias.
- `onMidiMessage(const uint8_t *data, size_t length)`: Función virtual que se llama cuando se recibe un mensaje MIDI. Debe ser sobrescrita para procesar el mensaje (por ejemplo, utilizando **MIDI_Handler**).
- **ESP32_BLE.h / ESP32_BLE.cpp**
Implementa el **servidor MIDI BLE**, permitiendo que el ESP32 reciba mensajes MIDI a través de Bluetooth Low Energy (BLE).
- **Funciones Clave:**
- `begin()`: Inicializa el servidor BLE y anuncia el servicio MIDI.
- `task()`: Procesa eventos BLE periódicamente.
- `setMidiMessageCallback()`: Configura un callback para procesar mensajes MIDI recibidos por BLE.
- `sendMidiMessage()`: Envía mensajes MIDI por BLE a dispositivos conectados.
- **MIDI_Handler.h / MIDI_Handler.cpp**
Proporciona funciones estáticas que interpretan datos MIDI sin procesar (después de eliminar el encabezado USB) en varios formatos:
- **Formato Raw:** Ej.: `[0x09, 0x90, 0x3C, 0x64]`
- **Formato Corto:** Ej.: `"90 3C 64"`
- **Número de Nota:** Ej.: `"60"`
- **Tipo de Mensaje:** Ej.: `"NoteOn"`, `"NoteOff"`, `"Control Change"`, `"Program Change"`, etc.
- **Estado:** Ej.: `"9n"`
- **Nota con Octava:** Ej.: `"C5"`
- **Vector de Mensaje:** Una estructura que agrega los campos interpretados.
- **displayhandler.h / displayhandler.cpp**
Gestiona la salida de la pantalla en el T-Display S3 utilizando la biblioteca LovyanGFX.
- **Funciones Clave:**
- `init()`: Inicializa la pantalla, establece la rotación (180°), dimensiones (320x170) y el tamaño de la fuente.
- `printMidiMessage(const char* message)`: Muestra el mensaje formateado en 5 líneas, con la última línea ("Octave") resaltada (línea separadora, fuente más grande y color diferente).
- `clear()`: Limpia la pantalla.
- **ESP32_Host_MIDI.ino**
Ejemplo de implementación para el T-Display S3. Integra la recepción de MIDI por USB, la recepción de MIDI BLE, la interpretación de datos (mediante **MIDI_Handler**) y la visualización de información.
- Utiliza una clase derivada que sobrescribe `onMidiMessage()` para:
- Eliminar el encabezado USB de los datos.
- Formatear los datos en 5 líneas (Raw, Short, Note#, Msg y Octave).
- Mostrar el mensaje y limpiar la pantalla después de 1 segundo.
### Ejemplo con Lilygo T-Display S3
El proyecto incluye ejemplos en la carpeta `examples/T-Display-S3/`, con código específico para esta placa.
Además, la carpeta `examples/T-Display-S3/images/` contiene imágenes ilustrativas de la funcionalidad del proyecto:
### Funcionamiento
1. **Recepción de MIDI USB-OTG en ESP32:**
Cuando se conecta un dispositivo MIDI por USB, el ESP32 captura los datos MIDI.
2. **Recepción de MIDI BLE:**
El ESP32 captura los datos MIDI recibidos por Bluetooth Low Energy (BLE) y los procesa en el servidor MIDI BLE.
3. **Interpretación:**
Se llama a la función virtual `onMidiMessage()`. Una clase derivada elimina el encabezado (primer byte) y utiliza **MIDI_Handler** para convertir los bytes en formatos legibles.
4. **Salida en Pantalla:**
El **DisplayHandler** muestra los datos formateados en 5 líneas (resaltando la última línea) en el T-Display S3, que está rotado 180° para la orientación correcta.
---
# ESP32_Host_MIDI 🎹📡
Progetto sviluppato per ARDUINO IDE:
Questo progetto fornisce una soluzione completa per ricevere, interpretare e visualizzare messaggi MIDI tramite USB e BLE sull'ESP32 (soprattutto ESP32-S3) con il T-Display S3.
---
## Italiano 🇮🇹 🍕
### Panoramica
La libreria **ESP32_Host_MIDI** consente all'ESP32 di funzionare come host USB per dispositivi MIDI, interpretare i dati in ingresso (utilizzando funzioni del modulo **MIDI_Handler**) e visualizzare queste informazioni sul T-Display S3 tramite **DisplayHandler**. Inoltre, la libreria supporta la comunicazione **BLE MIDI**, permettendo all'ESP32 di funzionare come **server MIDI BLE**.
La libreria è modulare, facilitando l'adattamento ad altri hardware regolando i file di configurazione.
### Struttura dei File
- **ESP32_Host_MIDI_Config.h**
Definisce i pin utilizzati per la comunicazione USB e il display.
- *Esempio:* `USB_DP_PIN`, `USB_DN_PIN`, `TFT_CS_PIN`, `TFT_DC_PIN`, `TFT_RST_PIN`, `TFT_BL_PIN`.
- **ESP32_Host_MIDI.h / ESP32_Host_MIDI.cpp**
Gestisce la comunicazione MIDI via USB.
- **Funzioni Principali:**
- `begin()`: Inizializza l'host USB e registra il client.
- `task()`: Elabora eventi USB ed esegue le trasferenze.
- `onMidiMessage(const uint8_t *data, size_t length)`: Funzione virtuale chiamata quando viene ricevuto un messaggio MIDI. Deve essere sovrascritta per elaborare il messaggio (ad esempio, utilizzando **MIDI_Handler**).
- **ESP32_BLE.h / ESP32_BLE.cpp**
Implementa il **server MIDI BLE**, consentendo all'ESP32 di ricevere messaggi MIDI tramite Bluetooth Low Energy (BLE).
- **Funzioni Principali:**
- `begin()`: Inizializza il server BLE e pubblicizza il servizio MIDI.
- `task()`: Elabora periodicamente gli eventi BLE.
- `setMidiMessageCallback()`: Imposta una callback per elaborare i messaggi MIDI ricevuti tramite BLE.
- `sendMidiMessage()`: Invia messaggi MIDI tramite BLE ai dispositivi connessi.
- **MIDI_Handler.h / MIDI_Handler.cpp**
Fornisce funzioni statiche che interpretano dati MIDI grezzi (dopo la rimozione dell'intestazione USB) in vari formati:
- **Formato Raw:** Es.: `[0x09, 0x90, 0x3C, 0x64]`
- **Formato Breve:** Es.: `"90 3C 64"`
- **Numero Nota:** Es.: `"60"`
- **Tipo di Messaggio:** Es.: `"NoteOn"`, `"NoteOff"`, `"Control Change"`, `"Program Change"`, ecc.
- **Stato:** Es.: `"9n"`
- **Nota con Ottava:** Es.: `"C5"`
- **Vettore di Messaggio:** Una struttura che aggrega i campi interpretati.
- **displayhandler.h / displayhandler.cpp**
Gestisce l'output del display sul T-Display S3 utilizzando la libreria LovyanGFX.
- **Funzioni Principali:**
- `init()`: Inizializza il display, imposta la rotazione (180°), le dimensioni (320x170) e la dimensione del carattere.
- `printMidiMessage(const char* message)`: Visualizza il messaggio formattato su 5 righe, con l'ultima riga ("Octave") evidenziata (linea separatrice, carattere più grande e colore diverso).
- `clear()`: Cancella il display.
- **ESP32_Host_MIDI.ino**
Esempio di implementazione per il T-Display S3. Integra la ricezione MIDI via USB, la ricezione MIDI BLE, l'interpretazione dei dati (tramite **MIDI_Handler**) e la visualizzazione delle informazioni.
- Utilizza una classe derivata che sovrascrive `onMidiMessage()` per:
- Rimuovere l'intestazione USB dai dati.
- Formattare i dati in 5 righe (Raw, Short, Note#, Msg e Octave).
- Mostrare il messaggio e cancellare lo schermo dopo 1 secondo.
### Esempio con Lilygo T-Display S3
Il progetto include esempi nella cartella `examples/T-Display-S3/`, con codice specifico per questa scheda.
Inoltre, la cartella `examples/T-Display-S3/images/` contiene immagini illustrative del funzionamento del progetto:
### Funzionamento
1. **Ricezione MIDI USB-OTG su ESP32:**
Quando un dispositivo MIDI viene connesso tramite USB, l'ESP32 cattura i dati MIDI.
2. **Ricezione MIDI BLE:**
L'ESP32 cattura i dati MIDI ricevuti tramite Bluetooth Low Energy (BLE) e li elabora nel server MIDI BLE.
3. **Interpretazione:**
Viene chiamata la funzione virtuale `onMidiMessage()`. Una classe derivata rimuove l'intestazione (primo byte) e utilizza **MIDI_Handler** per convertire i byte in formati leggibili.
4. **Output su Display:**
Il **DisplayHandler** visualizza i dati formattati su 5 righe (evidenziando l'ultima riga) sul T-Display S3, che è ruotato di 180° per la corretta orientazione.
---