# Espressif's additions to TinyUSB [](https://components.espressif.com/components/espressif/esp_tinyusb) This component adds features to TinyUSB that help users with integrating TinyUSB with their ESP-IDF application. It contains: * Configuration of USB device and string descriptors * USB Serial Device (CDC-ACM) with optional Virtual File System support * Input and output streams through USB Serial Device. This feature is available only when Virtual File System support is enabled. * Other USB classes (MIDI, MSC, HID…) support directly via TinyUSB * VBUS monitoring for self-powered devices * SPI Flash or sd-card access via MSC USB device Class. ## How to use? This component is distributed via [IDF component manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html). Just add `idf_component.yml` file to your main component with the following content: ``` yaml ## IDF Component Manager Manifest File dependencies: esp_tinyusb: "~1.0.0" ``` Or simply run: ``` idf.py add-dependency esp_tinyusb~1.0.0 ``` ## Documentation Hardware-related documentation could be found in [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/usb_device.html). ### Device Stack Structure The Device Stack is built on top of TinyUSB and provides: - Custom USB descriptor support - Serial device (CDC-ACM) support - Standard stream redirection through the serial device - Storage media support (SPI-Flash and SD-Card) for USB MSC Class - A dedicated task for TinyUSB servicing ### Configuration Options Configure the Device Stack using `menuconfig`: - TinyUSB log verbosity - Device Stack task options - Default device/string descriptor options - Class-specific options ### Descriptor Configuration Configure USB descriptors using the `tinyusb_config_t` structure: - `device_descriptor` - `string_descriptor` - `configuration_descriptor` (full-speed) - For high-speed devices: `fs_configuration_descriptor`, `hs_configuration_descriptor`, `qualifier_descriptor` If any descriptor field is set to `NULL`, default descriptors (based on menuconfig) are used. ### Installation Install the Device Stack by calling `tinyusb_driver_install` with a `tinyusb_config_t` structure. Members set to `0` or `NULL` use default values. ```c const tinyusb_config_t partial_init = { .device_descriptor = NULL, .string_descriptor = NULL, .external_phy = false, #if (TUD_OPT_HIGH_SPEED) .fs_configuration_descriptor = NULL, .hs_configuration_descriptor = NULL, .qualifier_descriptor = NULL, #else .configuration_descriptor = NULL, #endif }; ``` ### Self-Powered Device Self-powered devices must monitor VBUS voltage. Use a GPIO pin with a voltage divider or comparator to detect VBUS state. Set `self_powered = true` and assign the VBUS monitor GPIO in `tinyusb_config_t`. ### USB Serial Device (CDC-ACM) If enabled, initialize the USB Serial Device with `tusb_cdc_acm_init` and a `tinyusb_config_cdcacm_t` structure: ```c const tinyusb_config_cdcacm_t acm_cfg = { .usb_dev = TINYUSB_USBDEV_0, .cdc_port = TINYUSB_CDC_ACM_0, .rx_unread_buf_sz = 64, .callback_rx = NULL, .callback_rx_wanted_char = NULL, .callback_line_state_changed = NULL, .callback_line_coding_changed = NULL }; tusb_cdc_acm_init(&acm_cfg); ``` Redirect standard I/O streams to USB with `esp_tusb_init_console` and revert with `esp_tusb_deinit_console`. ### USB Mass Storage Device (MSC) If enabled, initialize storage media for MSC: **SPI-Flash Example:** ```c static esp_err_t storage_init_spiflash(wl_handle_t *wl_handle) { // ... partition and mount logic ... } storage_init_spiflash(&wl_handle); const tinyusb_msc_spiflash_config_t config_spi = { .wl_handle = wl_handle }; tinyusb_msc_storage_init_spiflash(&config_spi); ``` **SD-Card Example:** ```c static esp_err_t storage_init_sdmmc(sdmmc_card_t **card) { // ... SDMMC host and slot config ... } storage_init_sdmmc(&card); const tinyusb_msc_sdmmc_config_t config_sdmmc = { .card = card }; tinyusb_msc_storage_init_sdmmc(&config_sdmmc); ``` ### MSC Performance Optimization - **Single-buffer approach:** Buffer size is set via `CONFIG_TINYUSB_MSC_BUFSIZE`. - **Performance:** SD cards offer higher throughput than internal SPI flash due to architectural constraints. **Performance Table (ESP32-S3):** | FIFO Size | Read Speed | Write Speed | |-----------|------------|-------------| | 512 B | 0.566 MB/s | 0.236 MB/s | | 8192 B | 0.925 MB/s | 0.928 MB/s | **Performance Table (ESP32-P4):** | FIFO Size | Read Speed | Write Speed | |-----------|------------|-------------| | 512 B | 1.174 MB/s | 0.238 MB/s | | 8192 B | 4.744 MB/s | 2.157 MB/s | | 32768 B | 5.998 MB/s | 4.485 MB/s | **Performance Table (ESP32-S2, SPI Flash):** | FIFO Size | Write Speed | |-----------|-------------| | 512 B | 5.59 KB/s | | 8192 B | 21.54 KB/s | **Note:** Internal SPI flash is for demonstration only; use SD cards or external flash for higher performance. ## Examples You can find examples in [ESP-IDF on GitHub](https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/device).
b18c8e6daecfebc457a791e7155f263a12a4a726
idf.py add-dependency "espressif/esp_tinyusb^1.7.6~1"