espressif/esp_tinyusb

readme

# Espressif's additions to TinyUSB

[![Component Registry](https://components.espressif.com/components/espressif/esp_tinyusb/badge.svg)](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).