docs/reference/class_drivers.rst
Class Drivers
USB Class Drivers implement specific USB device classes (CDC, HID, MSC, MIDI, Audio, etc.) and are the main interface between the USB core and application code.
The MIDI 2.0 Device driver enables TinyUSB to act as a USB MIDI 2.0 device. It implements both Alt Setting 0 (MIDI 1.0 fallback) and Alt Setting 1 (native UMP) as required by the USB-MIDI 2.0 specification.
Key Features:
Enable MIDI 2.0 Device support in tusb_config.h:
.. code-block:: c
#define CFG_TUD_ENABLED 1 #define CFG_TUD_MIDI2 1
Optional configuration:
.. code-block:: c
#define CFG_TUD_MIDI2_TX_BUFSIZE 256 #define CFG_TUD_MIDI2_RX_BUFSIZE 256 #define CFG_TUD_MIDI2_TX_EPSIZE 64 #define CFG_TUD_MIDI2_RX_EPSIZE 64 #define CFG_TUD_MIDI2_NUM_GROUPS 1 // 1..16 #define CFG_TUD_MIDI2_NUM_FUNCTION_BLOCKS 1 // 1..32 #define CFG_TUD_MIDI2_EP_NAME "TinyUSB MIDI 2.0" #define CFG_TUD_MIDI2_PRODUCT_ID "TinyUSB-MIDI2"
Query Functions ^^^^^^^^^^^^^^^
.. code-block:: c
bool tud_midi2_mounted(void); uint32_t tud_midi2_available(void); uint8_t tud_midi2_alt_setting(void); bool tud_midi2_negotiated(void); uint8_t tud_midi2_protocol(void);
I/O Functions ^^^^^^^^^^^^^
.. code-block:: c
uint32_t tud_midi2_ump_read(uint32_t* words, uint32_t max_words); uint32_t tud_midi2_ump_write(const uint32_t* words, uint32_t count); uint32_t tud_midi2_packet_read(uint8_t packets[], uint32_t max_packets); uint32_t tud_midi2_packet_write(const uint8_t packets[], uint32_t count);
Callbacks ^^^^^^^^^
.. code-block:: c
void tud_midi2_rx_cb(uint8_t itf); void tud_midi2_set_itf_cb(uint8_t itf, uint8_t alt); bool tud_midi2_get_req_itf_cb(uint8_t rhport, const tusb_control_request_t* request);
The MIDI 2.0 Host driver enables TinyUSB to enumerate and communicate with USB MIDI 2.0 devices. It implements the USB MIDI 2.0 specification, supporting both MIDI 1.0 legacy devices and modern MIDI 2.0 devices with UMP (Universal MIDI Packet) protocol.
Key Features:
Enable MIDI 2.0 Host support in tusb_config.h:
.. code-block:: c
#define CFG_TUH_ENABLED 1 #define CFG_TUH_MIDI2 4 // Number of MIDI 2.0 devices to support
Optional buffer configuration:
.. code-block:: c
#define CFG_TUH_MIDI2_RX_BUFSIZE (4 * TUH_EPSIZE_BULK_MAX) #define CFG_TUH_MIDI2_TX_BUFSIZE (4 * TUH_EPSIZE_BULK_MAX)
When a MIDI 2.0 device is connected, the host stack invokes callbacks in this order:
.. code-block:: none
Device Connected | [Host detects Alt 0 and Alt 1 descriptors] | tuh_midi2_descriptor_cb() <- Device detected, NOT yet ready | [Auto-select highest protocol] | tuh_midi2_mount_cb() <- Device ready to use | [Application can read/write data] | tuh_midi2_rx_cb() <- Data arrived tuh_midi2_tx_cb() <- TX buffer space available | [Device disconnects] | tuh_midi2_umount_cb() <- Device removed
Query Functions ^^^^^^^^^^^^^^^
.. code-block:: c
bool tuh_midi2_mounted(uint8_t idx); uint8_t tuh_midi2_get_protocol_version(uint8_t idx); // 0=MIDI 1.0, 1=MIDI 2.0 uint8_t tuh_midi2_get_alt_setting_active(uint8_t idx); // 0 or 1 uint8_t tuh_midi2_get_cable_count(uint8_t idx);
I/O Functions ^^^^^^^^^^^^^
Read and write UMP (Universal MIDI Packet) data:
.. code-block:: c
uint32_t tuh_midi2_ump_read(uint8_t idx, uint32_t* words, uint32_t max_words); uint32_t tuh_midi2_ump_write(uint8_t idx, const uint32_t* words, uint32_t count); uint32_t tuh_midi2_write_flush(uint8_t idx);
Application can define weak callback implementations to respond to device events.
Descriptor Callback ^^^^^^^^^^^^^^^^^^^
Invoked when device is detected but not yet ready for I/O:
.. code-block:: c
void tuh_midi2_descriptor_cb(uint8_t idx, const tuh_midi2_descriptor_cb_t *desc_cb_data) { printf("MIDI %s device detected\r\n", desc_cb_data->protocol_version == 0 ? "1.0" : "2.0"); }
Mount Callback ^^^^^^^^^^^^^^
Invoked when device is ready for I/O:
.. code-block:: c
void tuh_midi2_mount_cb(uint8_t idx, const tuh_midi2_mount_cb_t *mount_cb_data) { printf("Device mounted at idx=%u, protocol=%u, alt_setting=%u\r\n", idx, mount_cb_data->protocol_version, mount_cb_data->alt_setting_active); }
RX Callback ^^^^^^^^^^^
Invoked when data arrives from device (both UMP packets and Stream Messages):
.. code-block:: c
void tuh_midi2_rx_cb(uint8_t idx, uint32_t xferred_bytes) { uint32_t words[4]; uint32_t n = tuh_midi2_ump_read(idx, words, 4);
for (uint32_t i = 0; i < n; i++) {
uint8_t mt = (words[i] >> 28) & 0x0F;
if (mt == 0x0F) {
// Stream Message - app handles discovery, negotiation, etc.
} else {
// Regular MIDI UMP packet
}
}
}
TX Callback ^^^^^^^^^^^
Invoked when TX buffer space becomes available:
.. code-block:: c
void tuh_midi2_tx_cb(uint8_t idx, uint32_t xferred_bytes) { // Buffer space available for writing }
Unmount Callback ^^^^^^^^^^^^^^^^
Invoked when device is disconnected:
.. code-block:: c
void tuh_midi2_umount_cb(uint8_t idx) { printf("Device at idx=%u disconnected\r\n", idx); }
.. code-block:: c
#include "tusb.h"
void tuh_midi2_mount_cb(uint8_t idx, const tuh_midi2_mount_cb_t *mount_cb_data) { printf("MIDI 2.0 device mounted\r\n"); }
void tuh_midi2_rx_cb(uint8_t idx, uint32_t xferred_bytes) { uint32_t words[4]; uint32_t n = tuh_midi2_ump_read(idx, words, 4);
for (uint32_t i = 0; i < n; i++) {
printf("RX: 0x%08lx\r\n", words[i]);
}
}
void tuh_midi2_umount_cb(uint8_t idx) { printf("MIDI 2.0 device disconnected\r\n"); }
int main(void) { board_init();
tusb_rhport_init_t host_init = {.role = TUSB_ROLE_HOST, .speed = TUSB_SPEED_AUTO};
tusb_init(BOARD_TUH_RHPORT, &host_init);
while (1) {
tuh_task();
}
}
The MIDI 2.0 Host driver uses a reactive, callback-driven architecture that mirrors the proven patterns in TinyUSB's existing device drivers (CDC, HID, etc.):
Differences from MIDI 1.0 Host ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table:: :header-rows: 1