USB Device Stack

Overview

The ESP-IDF USB Device Stack (hereinafter referred to as the Device Stack) enables USB Device support on ESP32-P4. By using the Device Stack, ESP32-P4 can be programmed with any well defined USB device functions (e.g., keyboard, mouse, camera), a custom function (aka vendor-specific class), or a combination of those functions (aka a composite device).

The Device Stack is built around the TinyUSB stack, but extends TinyUSB with some minor features and modifications for better integration with ESP-IDF. The Device stack is distributed as a managed component via the ESP Component Registry.

Features

  • 1 USB High-Speed (USB 2.0) peripheral with internal PHY

    • Endpoint 0 and 15 additional endpoints configurable as IN or OUT

    • Up to 8 IN endpoints (including Endpoint 0) concurrently active.

  • 1 USB Full-Speed (USB 1.1) peripheral with internal PHY

    • Endpoint 0 and 6 additional endpoints configurable as IN or OUT

    • Up to 5 IN endpoints (including Endpoint 0) concurrently active.

  • Multiple supported device classes (CDC, HID, MIDI, MSC…)

  • Vendor specific class

  • Composite devices

  • VBUS monitoring for self-powered devices

Hardware Connection

The ESP32-P4 routes the USB 2.0 peripheral D+ and D- signals to their dedicated pins. For USB device functionality, these pins must be connected to the bus (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug).

The ESP32-P4 routes the USB 1.1 peripheral D+ and D- signals to GPIOs 27 and 26 respectively. For USB device functionality, these GPIOs must be connected to the bus (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug).

Connection of an USB GPIOs directly to a USB standard-A plug

Note

Self-powered devices must also connect VBUS through a voltage divider or comparator. For more details, please refer to Self-Powered Device.

Device Stack Structure

The basis of the Device Stack is TinyUSB, where the Device Stack implements the following features on top of TinyUSB:

  • Customization of USB descriptors

  • Serial device support

  • Redirecting of standard streams through the Serial device

  • Storage Media (SPI-Flash and SD-Card) for USB Device MSC Class.

  • A task within the encapsulated device stack that handles TinyUSB servicing

Component Dependency

The Device Stack is distributed via the ESP Component Registry. Thus, to use it, please add the Device Stack component as dependency using the following command:

idf.py add-dependency esp_tinyusb

Configuration Options

Multiple aspects of the Device Stack can be configured using menuconfig. These include:

  • The verbosity of the TinyUSB’s log

  • Device Stack task related options

  • Default device/string descriptor options

  • Class specific options

The generated Kconfig reference for the available CONFIG_TINYUSB_* options is provided at the end of this document.

Descriptor Configuration

The tinyusb_config_t structure exposes USB descriptor settings through tinyusb_config_t::descriptor, which is a tinyusb_desc_config_t.

The following descriptors should be initialized for both full-speed and high-speed devices:

Full-speed devices should initialize the following field to provide their configuration descriptor:

High-speed devices should initialize the following fields to provide configuration descriptors at each speed:

Note

Both tinyusb_desc_config_t::full_speed_config and tinyusb_desc_config_t::high_speed_config must be present to comply with the USB 2.0 specification.

The Device Stack will instantiate a USB device based on the descriptors provided in the fields described above when tinyusb_driver_install() is called.

The Device Stack also provides default descriptors when the corresponding fields in tinyusb_desc_config_t are set to NULL. Their values come from menuconfig options such as CONFIG_TINYUSB_DESC_*. Default descriptors include:

Installation

To install the Device Stack, please call tinyusb_driver_install(). The Device Stack’s configuration is specified in a tinyusb_config_t structure that is passed as an argument to tinyusb_driver_install().

Note

Initialize tinyusb_config_t with TINYUSB_DEFAULT_CONFIG() and then override only the fields you need. Descriptor pointers left as NULL use the default descriptor values when available.

#include "tinyusb_default_config.h"

tinyusb_config_t tusb_cfg = TINYUSB_DEFAULT_CONFIG();
tusb_cfg.descriptor.device = NULL;
tusb_cfg.descriptor.string = NULL;
tusb_cfg.descriptor.full_speed_config = NULL;
#if (SOC_USB_OTG_PERIPH_NUM > 1)
    tusb_cfg.descriptor.high_speed_config = NULL;
    tusb_cfg.descriptor.qualifier = NULL;
#endif

ESP_ERROR_CHECK(tinyusb_driver_install(&tusb_cfg));

Self-Powered Device

USB specification mandates self-powered devices to monitor voltage levels on USB’s VBUS signal. As opposed to bus-powered devices, a self-powered device can be fully functional even without a USB connection. The self-powered device detects connection and disconnection events by monitoring the VBUS voltage level. VBUS is considered valid if it rises above 4.75 V and invalid if it falls below 4.35 V.

On the ESP32-P4, this will require using a GPIO to act as a voltage sensing pin to detect when VBUS goes above/below the prescribed thresholds. However, ESP32-P4 pins are 3.3 V tolerant. Thus, even if VBUS rises/falls above/below the thresholds mentioned above, it would still appear as a logic HIGH to the ESP32-P4. Thus, in order to detect the VBUS valid condition, users can do one of the following:

  • Connect VBUS to a voltage comparator chip/circuit that detects the thresholds described above (i.e., 4.35 V and 4.75 V), and outputs a 3.3 V logic level to the ESP32-P4 indicating whether VBUS is valid or not.

  • Use a resistor voltage divider that outputs (0.75 x Vdd) if VBUS is 4.4 V (see figure below).

Note

In either case, the voltage on the sensing pin must be logic low within 3 ms after the device is unplugged from the USB host.

Simple voltage divider for VBUS monitoring

Simple voltage divider for VBUS monitoring

To use this feature, set tinyusb_phy_config_t::self_powered to true and tinyusb_phy_config_t::vbus_monitor_io to the GPIO used for VBUS monitoring through tinyusb_config_t::phy.

USB Serial Device (CDC-ACM)

If CONFIG_TINYUSB_CDC_ENABLED is enabled in menuconfig, the USB Serial Device can be initialized with tinyusb_cdcacm_init() according to the settings from tinyusb_config_cdcacm_t, see the example below.

const tinyusb_config_cdcacm_t acm_cfg = {
    .cdc_port = TINYUSB_CDC_ACM_0,
    .callback_rx = NULL,
    .callback_rx_wanted_char = NULL,
    .callback_line_state_changed = NULL,
    .callback_line_coding_changed = NULL
};
ESP_ERROR_CHECK(tinyusb_cdcacm_init(&acm_cfg));

To specify callbacks, you can either set the pointer to your tusb_cdcacm_callback_t function in the configuration structure or call tinyusb_cdcacm_register_callback() after initialization.

USB Serial Console

The USB Serial Device allows the redirection of all standard input/output streams (stdin, stdout, stderr) to USB. Thus, calling standard library input/output functions such as printf() will result into the data being sent/received over USB instead of UART.

Users should call tinyusb_console_init() with the CDC interface number to switch the standard input/output streams to USB, and tinyusb_console_deinit() to switch them back to UART.

USB Mass Storage Device (MSC)

If CONFIG_TINYUSB_MSC_ENABLED is enabled in menuconfig, the ESP chip can be used as a USB MSC device. The storage media (SPI flash or SD card) can be initialized as shown below.

  • SPI-Flash

static esp_err_t storage_init_spiflash(wl_handle_t *wl_handle)
{
    ***
    esp_partition_t *data_partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_FAT, NULL);
    ***
    wl_mount(data_partition, wl_handle);
    ***
}
storage_init_spiflash(&wl_handle);

tinyusb_msc_storage_handle_t storage_hdl;
const tinyusb_msc_storage_config_t config_spi = {
    .medium.wl_handle = wl_handle,
};
ESP_ERROR_CHECK(tinyusb_msc_new_storage_spiflash(&config_spi, &storage_hdl));

  • SD-Card

static esp_err_t storage_init_sdmmc(sdmmc_card_t **card)
{
    ***
    sdmmc_host_t host = SDMMC_HOST_DEFAULT();
    sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT();
    // For SD Card, set bus width to use

    slot_config.width = 4;
    slot_config.clk = CONFIG_EXAMPLE_PIN_CLK;
    slot_config.cmd = CONFIG_EXAMPLE_PIN_CMD;
    slot_config.d0 = CONFIG_EXAMPLE_PIN_D0;
    slot_config.d1 = CONFIG_EXAMPLE_PIN_D1;
    slot_config.d2 = CONFIG_EXAMPLE_PIN_D2;
    slot_config.d3 = CONFIG_EXAMPLE_PIN_D3;
    slot_config.flags |= SDMMC_SLOT_FLAG_INTERNAL_PULLUP;

    *card = calloc(1, sizeof(sdmmc_card_t));
    ESP_ERROR_CHECK(sdmmc_host_init());
    ESP_ERROR_CHECK(sdmmc_host_init_slot(host.slot, &slot_config));
    ESP_ERROR_CHECK(sdmmc_card_init(&host, *card));
    ***
}
sdmmc_card_t *card = NULL;
storage_init_sdmmc(&card);

tinyusb_msc_storage_handle_t storage_hdl;
const tinyusb_msc_storage_config_t config_sdmmc = {
    .medium.card = card,
};
ESP_ERROR_CHECK(tinyusb_msc_new_storage_sdmmc(&config_sdmmc, &storage_hdl));

MSC Performance Optimization

Single-Buffer Approach

The single-buffer approach improves performance by using a dedicated buffer to temporarily store incoming write data instead of processing it immediately in the callback.

  • Configurable buffer size: The buffer size is set via CONFIG_TINYUSB_MSC_BUFSIZE, allowing users to balance performance and memory usage.

This approach ensures that USB transactions remain fast while avoiding potential delays caused by storage operations.

USB MSC Drive Performance

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 Limitations:

  • Internal SPI Flash performance is constrained by architectural limitations where program execution and storage access share the same flash chip. This results in program execution being suspended during flash writes, significantly impacting performance.

  • Internal SPI Flash usage is intended primarily for demonstration purposes. For practical use cases requiring higher performance, it is recommended to use external storage such as an SD card or an external SPI flash chip, where supported.

SD cards are not affected by this constraint, explaining their higher performance gains.

Application Examples

For better visibility, the examples can be found in ESP-IDF’s GitHub repository in the directory peripherals/usb/device.

  • tusb_console demonstrates how to set up ESP32-P4 to get log output via a Serial Device connection using the TinyUSB component, applicable for any Espressif boards that support USB-OTG.

  • tusb_serial_device demonstrates how to set up ESP32-P4 to function as a USB Serial Device using the TinyUSB component, with the ability to be configured as a double serial device.

  • tusb_midi demonstrates how to set up ESP32-P4 to function as a USB MIDI Device, outputting a MIDI note sequence via the native USB port using the TinyUSB component.

  • tusb_hid demonstrates how to implement a USB keyboard and mouse using the TinyUSB component, which sends ‘key a/A pressed & released’ events and moves the mouse in a square trajectory upon connection to a USB host.

  • tusb_msc demonstrates how to use the USB capabilities to create a Mass Storage Device that can be recognized by USB-hosts, allowing access to its internal data storage, with support for SPI Flash and SD MMC Card storage media.

  • tusb_composite_msc_serialdevice demonstrates how to set up ESP32-P4 to function simultaneously as both a USB Serial Device and an MSC device (SPI-Flash as the storage media) using the TinyUSB component.

API Reference

Header File

Functions

esp_err_t tinyusb_driver_install(const tinyusb_config_t *config)

Install the TinyUSB device driver and start the TinyUSB task.

This helper configures the USB PHY when requested, prepares descriptors, initializes the TinyUSB stack, and starts the TinyUSB task.

Note

When supplying a custom composite device descriptor with an Interface Association Descriptor, keep bDeviceClass as TUSB_CLASS_MISC and bDeviceSubClass as MISC_SUBCLASS_COMMON.

Parameters:

config – [in] TinyUSB stack configuration.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if config is NULL or contains unsupported port or task settings

  • ESP_ERR_INVALID_STATE if the TinyUSB device task is already running

  • ESP_ERR_NO_MEM if memory allocation fails during startup

  • Other error codes from TinyUSB task startup, USB PHY setup, or descriptor setup

esp_err_t tinyusb_driver_uninstall(void)

Uninstall the TinyUSB device driver.

This stops the TinyUSB task, tears down the TinyUSB stack, frees prepared descriptors, and deletes the USB PHY when it was created by tinyusb_driver_install().

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if the TinyUSB driver is not installed

  • Other error codes from TinyUSB task shutdown or USB PHY teardown

esp_err_t tinyusb_remote_wakeup(void)

Send a remote wakeup signal to the USB host.

Note

Call this function only while the device is suspended and the host has enabled remote wakeup.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if remote wakeup is not enabled by the host

  • ESP_FAIL if the remote wakeup request cannot be sent

Structures

struct tinyusb_phy_config_t

TinyUSB PHY and VBUS monitoring configuration.

Note

On the ESP32-P4 high-speed port, install the GPIO ISR service with gpio_install_isr_service() before calling tinyusb_driver_install() when VBUS monitoring is enabled.

Public Members

bool skip_setup

Skip automatic USB PHY setup. Set this when the application configures the PHY manually, for example when using an external PHY.

bool self_powered

Enable VBUS monitoring for a self-powered device.

int vbus_monitor_io

GPIO used to monitor VBUS. Ignored when self_powered is false.

struct tinyusb_task_config_t

TinyUSB task configuration.

Public Members

size_t size

USB device task stack size in bytes.

uint8_t priority

USB device task priority.

int xCoreID

USB device task core affinity.

struct tinyusb_desc_config_t

USB device descriptor configuration.

Any descriptor pointer may be set to NULL to use the default descriptor supplied by esp_tinyusb when one is available for the selected class and speed.

Note

All non-NULL pointers must remain valid for the lifetime of the TinyUSB device stack.

Public Members

const tusb_desc_device_t *device

Device descriptor.

const tusb_desc_device_qualifier_t *qualifier

Device qualifier descriptor for high-speed-capable devices.

const char **string

Array of string descriptor pointers.

int string_count

Number of entries in string.

const uint8_t *full_speed_config

Full-speed configuration descriptor.

const uint8_t *high_speed_config

High-speed configuration descriptor.

struct tinyusb_event_t

TinyUSB device event data passed to tinyusb_event_cb_t.

Public Members

tinyusb_event_id_t id

Event identifier.

uint8_t rhport

USB peripheral port number.

bool remote_wakeup

true when the host enabled remote wakeup for the suspended device.

struct tinyusb_event_t suspended

Data for TINYUSB_EVENT_SUSPENDED.

struct tinyusb_config_t

TinyUSB driver configuration.

Public Members

tinyusb_port_t port

USB peripheral port to use.

tinyusb_phy_config_t phy

USB PHY configuration.

tinyusb_task_config_t task

USB device task configuration.

tinyusb_desc_config_t descriptor

USB descriptor configuration.

tinyusb_event_cb_t event_cb

Optional event callback.

void *event_arg

User argument passed to event_cb.

Macros

TINYUSB_ESPRESSIF_VID

TinyUSB vendor ID used by the default device descriptor.

Type Definitions

typedef void (*tinyusb_event_cb_t)(tinyusb_event_t *event, void *arg)

Callback invoked on TinyUSB device events.

Param event:

[in] Pointer to the event data.

Param arg:

[in] User argument from tinyusb_config_t.event_arg.

Enumerations

enum tinyusb_port_t

TinyUSB peripheral port identifier.

Values:

enumerator TINYUSB_PORT_FULL_SPEED_0

USB OTG 1.1 peripheral port.

enumerator TINYUSB_PORT_MAX

Number of supported peripheral ports.

enum tinyusb_event_id_t

TinyUSB device event identifier.

Values:

enumerator TINYUSB_EVENT_ATTACHED

The USB device has been attached to the host.

enumerator TINYUSB_EVENT_DETACHED

The USB device has been detached from the host.

Header File

Macros

TINYUSB_DEFAULT_CONFIG(...)

Initialize a TinyUSB driver configuration with target defaults.

Supported invocations are:

  • TINYUSB_DEFAULT_CONFIG()

  • TINYUSB_DEFAULT_CONFIG(event_cb)

  • TINYUSB_DEFAULT_CONFIG(event_cb, event_arg)

The default port is TINYUSB_PORT_HIGH_SPEED_0 on ESP32-P4 and TINYUSB_PORT_FULL_SPEED_0 on other supported targets. The default task settings come from TINYUSB_TASK_DEFAULT().

TINYUSB_DEFAULT_TASK_AFFINITY

Default TinyUSB task affinity.

The default task runs on CPU0 in unicore builds and CPU1 in multicore builds.

TINYUSB_DEFAULT_TASK_SIZE

Default TinyUSB task stack size in bytes.

TINYUSB_DEFAULT_TASK_PRIO

Default TinyUSB task priority.

TINYUSB_CONFIG_FULL_SPEED(event_hdl, arg)

Initialize a full-speed TinyUSB driver configuration.

The resulting initializer uses the default PHY settings, default task settings from TINYUSB_TASK_DEFAULT(), and empty descriptor pointers so the stack can fall back to built-in defaults when available.

Parameters:
TINYUSB_CONFIG_HIGH_SPEED(event_hdl, arg)

Initialize a high-speed TinyUSB driver configuration.

The resulting initializer uses the default PHY settings, default task settings from TINYUSB_TASK_DEFAULT(), and empty descriptor pointers so the stack can fall back to built-in defaults when available.

Parameters:
TINYUSB_TASK_DEFAULT()

Initialize a TinyUSB task configuration with default values.

TINYUSB_TASK_CUSTOM(s, p, a)

Initialize a custom TinyUSB task configuration.

Parameters:

  • s – Task stack size in bytes.

  • p – Task priority.

  • a – Task affinity.

Header File

Functions

esp_err_t tinyusb_cdcacm_init(const tinyusb_config_cdcacm_t *cfg)

Initialize a CDC ACM interface.

Parameters:

cfg – [in] CDC ACM configuration. Must not be NULL.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if the selected CDC interface is already initialized

  • Other error codes from the underlying CDC initialization

esp_err_t tinyusb_cdcacm_deinit(int itf)

Deinitialize a CDC ACM interface.

Parameters:

itf – [in] CDC ACM interface number.

Returns:

  • ESP_OK on success

  • Other error codes from the underlying CDC deinitialization

esp_err_t tinyusb_cdcacm_register_callback(tinyusb_cdcacm_itf_t itf, cdcacm_event_type_t event_type, tusb_cdcacm_callback_t callback)

Register a CDC ACM event callback.

If a callback is already registered for the selected event, it is replaced.

Parameters:

  • itf – [in] CDC ACM interface number.

  • event_type – [in] Event to associate with the callback.

  • callback – [in] Callback function, or NULL to disable the callback for the selected event.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if event_type is invalid

  • ESP_ERR_INVALID_STATE if the interface is not initialized

esp_err_t tinyusb_cdcacm_unregister_callback(tinyusb_cdcacm_itf_t itf, cdcacm_event_type_t event_type)

Unregister a CDC ACM event callback.

Parameters:

  • itf – [in] CDC ACM interface number.

  • event_type – [in] Event whose callback should be removed.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if event_type is invalid

  • ESP_ERR_INVALID_STATE if the interface is not initialized

size_t tinyusb_cdcacm_write_queue_char(tinyusb_cdcacm_itf_t itf, char ch)

Queue one character for transmission.

Parameters:

  • itf – [in] CDC ACM interface number.

  • ch – [in] Character to queue.

Returns:

Number of bytes queued. Returns 0 if the interface is not initialized or the TX buffer cannot accept more data.

size_t tinyusb_cdcacm_write_queue(tinyusb_cdcacm_itf_t itf, const uint8_t *in_buf, size_t in_size)

Queue data for transmission.

Parameters:

  • itf – [in] CDC ACM interface number.

  • in_buf – [in] Input buffer.

  • in_size – [in] Input buffer size in bytes.

Returns:

Number of bytes queued. Returns 0 if the interface is not initialized.

esp_err_t tinyusb_cdcacm_write_flush(tinyusb_cdcacm_itf_t itf, uint32_t timeout_ticks)

Flush queued data from a CDC ACM TX buffer.

Use tinyusb_cdcacm_write_queue() to add data to the buffer before calling this function.

Note

Avoid calling this function with a timeout from CDC callbacks. TinyUSB may defer endpoint flushing until callback processing completes, which can cause the flush to block until the timeout expires.

Parameters:

  • itf – [in] CDC ACM interface number.

  • timeout_ticks – [in] Flush timeout in RTOS ticks. Set to 0 for non-blocking mode.

Returns:

  • ESP_OK on success

  • ESP_ERR_NOT_FINISHED if data is still pending in non-blocking mode

  • ESP_ERR_TIMEOUT if the timeout expires before the flush completes

  • ESP_FAIL if the interface is not initialized

esp_err_t tinyusb_cdcacm_read(tinyusb_cdcacm_itf_t itf, uint8_t *out_buf, size_t out_buf_sz, size_t *rx_data_size)

Read received data from a CDC ACM interface.

Parameters:

  • itf – [in] CDC ACM interface number.

  • out_buf – [out] Output buffer. Must point to writable memory when out_buf_sz is greater than 0.

  • out_buf_sz – [in] Output buffer size in bytes.

  • rx_data_size – [out] Number of bytes written to out_buf. Must not be NULL.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if the interface is not initialized

bool tinyusb_cdcacm_initialized(tinyusb_cdcacm_itf_t itf)

Check whether a CDC ACM interface is initialized.

Parameters:

itf – [in] CDC ACM interface number.

Returns:

true if the interface is initialized, otherwise false.

Structures

struct cdcacm_event_rx_wanted_char_data_t

Event data for CDC_EVENT_RX_WANTED_CHAR.

Public Members

char wanted_char

Requested character that triggered the callback.

struct cdcacm_event_line_state_changed_data_t

Event data for CDC_EVENT_LINE_STATE_CHANGED.

Public Members

bool dtr

Data Terminal Ready line state.

bool rts

Request To Send line state.

struct cdcacm_event_line_coding_changed_data_t

Event data for CDC_EVENT_LINE_CODING_CHANGED.

Public Members

cdc_line_coding_t const *p_line_coding

Updated line coding value.

struct cdcacm_event_t

CDC ACM event data passed to tusb_cdcacm_callback_t.

Public Members

cdcacm_event_type_t type

Event type.

cdcacm_event_rx_wanted_char_data_t rx_wanted_char_data

Data for CDC_EVENT_RX_WANTED_CHAR.

cdcacm_event_line_state_changed_data_t line_state_changed_data

Data for CDC_EVENT_LINE_STATE_CHANGED.

cdcacm_event_line_coding_changed_data_t line_coding_changed_data

Data for CDC_EVENT_LINE_CODING_CHANGED.

struct tinyusb_config_cdcacm_t

CDC ACM configuration.

Public Members

tinyusb_cdcacm_itf_t cdc_port

CDC ACM interface to initialize.

tusb_cdcacm_callback_t callback_rx

Optional callback for CDC_EVENT_RX.

tusb_cdcacm_callback_t callback_rx_wanted_char

Optional callback for CDC_EVENT_RX_WANTED_CHAR.

tusb_cdcacm_callback_t callback_line_state_changed

Optional callback for CDC_EVENT_LINE_STATE_CHANGED.

tusb_cdcacm_callback_t callback_line_coding_changed

Optional callback for CDC_EVENT_LINE_CODING_CHANGED.

Type Definitions

typedef void (*tusb_cdcacm_callback_t)(int itf, cdcacm_event_t *event)

CDC ACM event callback type.

Param itf:

[in] CDC ACM interface number.

Param event:

[in] Event data.

Enumerations

enum tinyusb_cdcacm_itf_t

CDC ACM interface identifier.

Values:

enumerator TINYUSB_CDC_ACM_0

CDC ACM interface 0.

enumerator TINYUSB_CDC_ACM_1

CDC ACM interface 1.

enumerator TINYUSB_CDC_ACM_MAX

Number of CDC ACM interfaces.

enum cdcacm_event_type_t

CDC ACM event identifier.

Values:

enumerator CDC_EVENT_RX

RX data is available.

enumerator CDC_EVENT_RX_WANTED_CHAR

The requested character was received.

enumerator CDC_EVENT_LINE_STATE_CHANGED

DTR or RTS changed.

enumerator CDC_EVENT_LINE_CODING_CHANGED

Line coding changed.

Header File

Functions

esp_err_t tinyusb_console_init(int cdc_intf)

Redirect the standard console streams to a TinyUSB CDC interface.

Parameters:

cdc_intf – [in] TinyUSB CDC interface number to register as the console.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if the selected CDC interface is not initialized

  • ESP_FAIL if stdio redirection fails

  • Other error codes from VFS registration

esp_err_t tinyusb_console_deinit(int cdc_intf)

Restore the standard console streams.

Call this function only after a successful call to tinyusb_console_init().

Parameters:

cdc_intf – [in] CDC interface number kept for API symmetry with tinyusb_console_init().

Returns:

  • ESP_OK on success

  • ESP_FAIL if restoring the standard streams fails

Header File

Functions

esp_err_t tinyusb_msc_install_driver(const tinyusb_msc_driver_config_t *config)

Install the TinyUSB MSC driver.

Parameters:

config – [in] Driver configuration. Must not be NULL.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if config is NULL

  • ESP_ERR_INVALID_STATE if the driver is already installed

  • ESP_ERR_NO_MEM if memory allocation fails

esp_err_t tinyusb_msc_uninstall_driver(void)

Uninstall the TinyUSB MSC driver.

Returns:

  • ESP_OK on success

  • ESP_ERR_NOT_SUPPORTED if the driver is not installed

  • ESP_ERR_INVALID_STATE if one or more storage instances are still present

esp_err_t tinyusb_msc_new_storage_spiflash(const tinyusb_msc_storage_config_t *config, tinyusb_msc_storage_handle_t *handle)

Create a TinyUSB MSC storage instance backed by SPI flash.

Parameters:

  • config – [in] Storage configuration. Must not be NULL.

  • handle – [out] Optional output for the created storage handle.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if config is NULL or config->medium.wl_handle is invalid

  • ESP_ERR_NOT_SUPPORTED if the TinyUSB MSC buffer is smaller than the wear levelling sector size

  • ESP_ERR_NO_MEM if memory allocation fails

  • ESP_FAIL if the storage cannot be mapped to a LUN

  • Other error codes from driver installation, storage medium setup, or filesystem mounting

esp_err_t tinyusb_msc_delete_storage(tinyusb_msc_storage_handle_t handle)

Delete a TinyUSB MSC storage instance.

Parameters:

handle – [in] Storage handle returned by a storage creation function.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if handle is NULL

  • ESP_ERR_INVALID_STATE if the driver is not installed, no storage exists, or deferred writes are pending

  • ESP_ERR_NOT_FOUND if the storage is not mapped to any LUN

esp_err_t tinyusb_msc_set_storage_callback(tusb_msc_callback_t callback, void *arg)

Set the TinyUSB MSC storage event callback.

Parameters:

  • callback – [in] Callback function.

  • arg – [in] User argument passed to the callback.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if the driver is not installed

  • ESP_ERR_INVALID_ARG if callback is NULL

esp_err_t tinyusb_msc_format_storage(tinyusb_msc_storage_handle_t handle)

Format a storage instance with a FAT filesystem.

Note

This function erases all data on the storage media.

Note

The storage must be mounted to TINYUSB_MSC_STORAGE_MOUNT_APP.

Parameters:

handle – [in] Storage handle returned by a storage creation function.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if the MSC driver is not initialized

  • ESP_ERR_INVALID_ARG if handle is NULL or the storage is not mounted to the application

  • ESP_ERR_NOT_FOUND if the media is not in the expected unformatted state

  • Other error codes from disk I/O, VFS, or FAT filesystem operations

esp_err_t tinyusb_msc_config_storage_fat_fs(tinyusb_msc_storage_handle_t handle, tinyusb_msc_fatfs_config_t *fatfs_config)

Update FAT filesystem parameters for a storage instance.

Parameters:

  • handle – [in] Storage handle returned by a storage creation function.

  • fatfs_config – [in] FAT filesystem configuration.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if fatfs_config is NULL

  • ESP_ERR_INVALID_STATE if the MSC driver or storage is not initialized

esp_err_t tinyusb_msc_set_storage_mount_point(tinyusb_msc_storage_handle_t handle, tinyusb_msc_mount_point_t mount_point)

Request the active mount point for a storage instance.

This function requests switching storage ownership between the application and the USB host.

Note

This function does not propagate failures from the internal mount/unmount helpers to the caller.

Parameters:

  • handle – [in] Storage handle returned by a storage creation function.

  • mount_point – [in] Requested mount point.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if the MSC driver is not installed

esp_err_t tinyusb_msc_get_storage_capacity(tinyusb_msc_storage_handle_t handle, uint32_t *sector_count)

Get the storage capacity in sectors.

Parameters:

  • handle – [in] Storage handle returned by a storage creation function.

  • sector_count – [out] Number of sectors in the storage medium.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if sector_count is NULL

  • ESP_ERR_INVALID_STATE if the MSC driver or storage is not initialized

esp_err_t tinyusb_msc_get_storage_sector_size(tinyusb_msc_storage_handle_t handle, uint32_t *sector_size)

Get the storage sector size in bytes.

Parameters:

  • handle – [in] Storage handle returned by a storage creation function.

  • sector_size – [out] Sector size in bytes.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if sector_size is NULL

  • ESP_ERR_INVALID_STATE if the MSC driver or storage is not initialized

esp_err_t tinyusb_msc_get_storage_mount_point(tinyusb_msc_storage_handle_t handle, tinyusb_msc_mount_point_t *mount_point)

Get the current mount point of a storage instance.

Parameters:

  • handle – [in] Storage handle returned by a storage creation function.

  • mount_point – [out] Current mount point.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if mount_point is NULL

  • ESP_ERR_INVALID_STATE if the MSC driver or storage is not initialized

Structures

struct tinyusb_msc_event_t

TinyUSB MSC event data passed to tusb_msc_callback_t.

Public Members

tinyusb_msc_event_id_t id

Event identifier.

tinyusb_msc_mount_point_t mount_point

Mount point associated with the event.

struct tinyusb_msc_event_t event_data

Reserved for future event-specific data.

bool is_mounted

true when the storage is mounted.

struct tinyusb_msc_event_t mount_changed_data

Deprecated compatibility field.

struct tinyusb_msc_fatfs_config_t

FAT filesystem configuration for a TinyUSB MSC storage instance.

Public Members

char *base_path

Filesystem mount path. Set to NULL to use the default component path.

esp_vfs_fat_mount_config_t config

FAT mount configuration.

bool do_not_format

If true, fail instead of formatting media with no filesystem.

BYTE format_flags

FatFs format flags. Set to 0 to use FM_ANY.

struct tinyusb_msc_storage_config_t

TinyUSB MSC storage configuration.

Public Members

wl_handle_t wl_handle

Wear levelling handle for SPI flash storage.

union tinyusb_msc_storage_config_t medium

Storage medium selector.

tinyusb_msc_fatfs_config_t fat_fs

FAT filesystem configuration.

tinyusb_msc_mount_point_t mount_point

Requested initial storage owner after creation.

struct tinyusb_msc_driver_config_t

TinyUSB MSC driver configuration.

Public Members

uint16_t auto_mount_off

Disable automatic remounting on USB connect and disconnect.

uint16_t reserved15

Reserved, set to 0.

uint16_t val

Raw flag value.

union tinyusb_msc_driver_config_t user_flags

Driver flags.

tusb_msc_callback_t callback

Optional storage event callback.

void *callback_arg

User argument passed to callback.

Type Definitions

typedef struct tinyusb_msc_storage_s *tinyusb_msc_storage_handle_t

Opaque handle for a TinyUSB MSC storage instance.

typedef void (*tusb_msc_callback_t)(tinyusb_msc_storage_handle_t handle, tinyusb_msc_event_t *event, void *arg)

TinyUSB MSC event callback type.

Param handle:

[in] Storage handle associated with the event.

Param event:

[in] Event data.

Param arg:

[in] User argument configured for the callback.

Enumerations

enum tinyusb_msc_mount_point_t

TinyUSB MSC storage mount point.

Values:

enumerator TINYUSB_MSC_STORAGE_MOUNT_USB

Storage is exposed to the USB host.

enumerator TINYUSB_MSC_STORAGE_MOUNT_APP

Storage is mounted for local application use.

enum tinyusb_msc_event_id_t

TinyUSB MSC event identifier.

Values:

enumerator TINYUSB_MSC_EVENT_MOUNT_START

Mount or unmount operation is starting.

enumerator TINYUSB_MSC_EVENT_MOUNT_COMPLETE

Mount or unmount operation completed successfully.

enumerator TINYUSB_MSC_EVENT_MOUNT_FAILED

Mount or unmount operation failed.

enumerator TINYUSB_MSC_EVENT_FORMAT_REQUIRED

Formatting is required before the filesystem can be mounted.

enumerator TINYUSB_MSC_EVENT_FORMAT_FAILED

Formatting failed.

Header File

Functions

esp_err_t tinyusb_net_init(const tinyusb_net_config_t *cfg)

Initialize the TinyUSB NET driver.

Parameters:

cfg – [in] Driver configuration. Must not be NULL.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if the TinyUSB NET driver is already initialized

void tinyusb_net_deinit(void)

Deinitialize the TinyUSB NET driver.

esp_err_t tinyusb_net_send_sync(void *buffer, uint16_t len, void *buff_free_arg, TickType_t timeout)

Send a packet synchronously through the TinyUSB NET interface.

Note

Synchronous and asynchronous sends can be mixed.

Note

The first synchronous send allocates synchronization primitives, which increases heap usage.

Parameters:

  • buffer – [in] Packet payload buffer.

  • len – [in] Packet length in bytes.

  • buff_free_arg – [in] User token passed to free_tx_buffer, typically the packet buffer pointer.

  • timeout – [in] Timeout in RTOS ticks.

Returns:

  • ESP_OK if the packet is accepted by TinyUSB for transmission

  • ESP_FAIL if the USB interface cannot accept the packet

  • ESP_ERR_TIMEOUT if the transmission does not complete before timeout

  • ESP_ERR_INVALID_STATE if the TinyUSB NET interface is not mounted

  • ESP_ERR_NO_MEM if internal synchronization objects cannot be allocated

esp_err_t tinyusb_net_send_async(void *buffer, uint16_t len, void *buff_free_arg)

Queue a packet for asynchronous transmission through the TinyUSB NET interface.

Note

When using asynchronous sends, free the packet through free_tx_buffer or another application-managed path.

Note

Synchronous and asynchronous sends can be mixed.

Note

ESP_OK means the packet was queued for processing in the TinyUSB task. It does not guarantee that the USB interface accepted the packet.

Parameters:

  • buffer – [in] Packet payload buffer.

  • len – [in] Packet length in bytes.

  • buff_free_arg – [in] User token passed to free_tx_buffer, typically the packet buffer pointer.

Returns:

  • ESP_OK if the packet is queued for deferred processing

  • ESP_ERR_INVALID_STATE if the TinyUSB NET interface is not mounted

Structures

struct tinyusb_net_config_t

TinyUSB NET driver configuration.

Public Members

uint8_t mac_addr[6]

Device MAC address.

tusb_net_rx_cb_t on_recv_callback

Optional receive callback.

tusb_net_free_tx_cb_t free_tx_buffer

Optional callback used to release TX buffers or user tokens. Required when the application needs asynchronous send cleanup.

tusb_net_init_cb_t on_init_callback

Optional callback invoked from tud_network_init_cb().

void *user_context

User context passed to every callback.

Type Definitions

typedef esp_err_t (*tusb_net_rx_cb_t)(void *buffer, uint16_t len, void *ctx)

TinyUSB NET receive callback type.

Param buffer:

[in] Pointer to the received packet payload.

Param len:

[in] Packet length in bytes.

Param ctx:

[in] User context from tinyusb_net_config_t.user_context.

Return:

The return value is currently ignored by esp_tinyusb.

typedef void (*tusb_net_free_tx_cb_t)(void *buffer, void *ctx)

TinyUSB NET TX buffer release callback type.

Param buffer:

[in] User token passed as buff_free_arg to the send function.

Param ctx:

[in] User context from tinyusb_net_config_t.user_context.

typedef void (*tusb_net_init_cb_t)(void *ctx)

TinyUSB NET initialization callback type.

Param ctx:

[in] User context from tinyusb_net_config_t.user_context.

Header File

Functions

esp_err_t esp_vfs_tusb_cdc_register(int cdc_intf, char const *path)

Register a TinyUSB CDC interface in VFS.

Only one TinyUSB CDC interface can be registered in VFS at a time.

Parameters:

  • cdc_intf – [in] TinyUSB CDC interface number.

  • path – [in] VFS path to register. Set to NULL to use VFS_TUSB_PATH_DEFAULT.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE if the selected CDC interface is not initialized

  • ESP_ERR_INVALID_ARG if path is too long

  • Other error codes from VFS registration

esp_err_t esp_vfs_tusb_cdc_unregister(char const *path)

Unregister a TinyUSB CDC interface from VFS.

Parameters:

path – [in] VFS path to unregister. Set to NULL to use VFS_TUSB_PATH_DEFAULT.

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if path does not match the registered TinyUSB VFS path

  • Other error codes from VFS unregistration

void esp_vfs_tusb_cdc_set_tx_line_endings(esp_line_endings_t mode)

Set the transmitted line ending conversion mode.

This controls how newline characters (\n) written to stdout are converted before they are sent over the TinyUSB CDC VFS stream:

  • ESP_LINE_ENDINGS_CRLF: convert LF to CRLF

  • ESP_LINE_ENDINGS_CR: convert LF to CR

  • ESP_LINE_ENDINGS_LF: no modification

Parameters:

mode – [in] Line ending conversion mode.

void esp_vfs_tusb_cdc_set_rx_line_endings(esp_line_endings_t mode)

Set the received line ending conversion mode.

This controls how line endings received from the TinyUSB CDC VFS stream are converted before they are passed to stdin as newline characters (\n):

  • ESP_LINE_ENDINGS_CRLF: convert CRLF to LF

  • ESP_LINE_ENDINGS_CR: convert CR to LF

  • ESP_LINE_ENDINGS_LF: no modification

Parameters:

mode – [in] Line ending conversion mode.

Macros

VFS_TUSB_MAX_PATH

Maximum VFS path length, including the terminating null byte.

VFS_TUSB_PATH_DEFAULT

Default VFS path used for TinyUSB CDC registration.

Kconfig Reference

The generated Kconfig reference below documents the available CONFIG_TINYUSB_* options for esp_tinyusb, including descriptor defaults and class-specific settings.

TinyUSB Stack

Contains:

CONFIG_TINYUSB_DEBUG_LEVEL

TinyUSB log level (0-3)

Found in: TinyUSB Stack

Specify verbosity of TinyUSB log output.

Range:

  • from 0 to 3

Default value:

  • 1

TinyUSB DCD

Contains:

CONFIG_TINYUSB_MODE

DCD Mode

Found in: TinyUSB Stack > TinyUSB DCD

TinyUSB DCD DWC2 Driver supports two modes: Slave mode (based on IRQ) and Buffer DMA mode.

Available options:

  • Slave/IRQ (CONFIG_TINYUSB_MODE_SLAVE)

  • Buffer DMA (CONFIG_TINYUSB_MODE_DMA)

TinyUSB callbacks

Contains:

CONFIG_TINYUSB_SUSPEND_CALLBACK

Register suspend callback

Found in: TinyUSB Stack > TinyUSB callbacks

Register TinyUSB’s suspend callback (tud_suspend_cb()) in esp_tinyusb.

When enabled, esp_tinyusb provides a strong implementation of tud_suspend_cb() and dispatches TINYUSB_EVENT_SUSPENDED via the esp_tinyusb device event callback.

When disabled, tinyusb provides weak implementation of the tud_suspend_cb(), and user can provide it’s own strong implementation of the tud_suspend_cb().

NOTE: When this option is enabled, user applications MUST NOT define tud_suspend_cb() themselves. Defining tud_suspend_cb() in the application while this option is enabled will result in a linker error due to multiple definitions.

Default value:

  • No (disabled)

CONFIG_TINYUSB_RESUME_CALLBACK

Register resume callback

Found in: TinyUSB Stack > TinyUSB callbacks

Register TinyUSB’s resume callback (tud_resume_cb()) in esp_tinyusb.

When enabled, esp_tinyusb provides a strong implementation of tud_resume_cb() and dispatches TINYUSB_EVENT_RESUMED via the esp_tinyusb device event callback.

When disabled, tinyusb provides weak implementation of the tud_resume_cb(), and user can provide it’s own strong implementation of the tud_resume_cb().

NOTE: When this option is enabled, user applications MUST NOT define tud_resume_cb() themselves. Defining tud_resume_cb() in the application while this option is enabled will result in a linker error due to multiple definitions.

Default value:

  • No (disabled)

Descriptor configuration

Contains:

CONFIG_TINYUSB_DESC_USE_ESPRESSIF_VID

VID: Use Espressif’s vendor ID

Found in: TinyUSB Stack > Descriptor configuration

Enable this option, USB device will use Espressif’s vendor ID as its VID. This is helpful at product develop stage.

Default value:

  • Yes (enabled)

CONFIG_TINYUSB_DESC_CUSTOM_VID

VID: Custom vendor ID

Found in: TinyUSB Stack > Descriptor configuration

Custom Vendor ID.

CONFIG_TINYUSB_DESC_USE_DEFAULT_PID

PID: Use a default PID assigned to TinyUSB

Found in: TinyUSB Stack > Descriptor configuration

Default TinyUSB PID assigning uses values 0x4000…0x4007.

Default value:

  • Yes (enabled)

CONFIG_TINYUSB_DESC_CUSTOM_PID

PID: Custom product ID

Found in: TinyUSB Stack > Descriptor configuration

Custom Product ID.

CONFIG_TINYUSB_DESC_BCD_DEVICE

bcdDevice

Found in: TinyUSB Stack > Descriptor configuration

Version of the firmware of the USB device.

Default value:

  • “0x0100”

CONFIG_TINYUSB_DESC_MANUFACTURER_STRING

Manufacturer name

Found in: TinyUSB Stack > Descriptor configuration

Name of the manufacturer of the USB device.

Default value:

  • “Espressif Systems”

CONFIG_TINYUSB_DESC_PRODUCT_STRING

Product name

Found in: TinyUSB Stack > Descriptor configuration

Name of the USB device.

Default value:

  • “Espressif Device”

CONFIG_TINYUSB_DESC_SERIAL_STRING

Serial string

Found in: TinyUSB Stack > Descriptor configuration

Serial number of the USB device.

Default value:

  • 123456

CONFIG_TINYUSB_DESC_CDC_STRING

CDC Device String

Found in: TinyUSB Stack > Descriptor configuration

Name of the CDC device.

Default value:

CONFIG_TINYUSB_DESC_MSC_STRING

MSC Device String

Found in: TinyUSB Stack > Descriptor configuration

Name of the MSC device.

Default value:

Mass Storage Class (MSC)

Contains:

CONFIG_TINYUSB_MSC_ENABLED

Enable TinyUSB MSC feature

Found in: TinyUSB Stack > Mass Storage Class (MSC)

Enable TinyUSB MSC feature.

Default value:

  • No (disabled)

CONFIG_TINYUSB_MSC_BUFSIZE

MSC FIFO size

Found in: TinyUSB Stack > Mass Storage Class (MSC) > CONFIG_TINYUSB_MSC_ENABLED

MSC FIFO size, in bytes.

Range:
Default value:
CONFIG_TINYUSB_MSC_MOUNT_PATH

Mount Path

Found in: TinyUSB Stack > Mass Storage Class (MSC) > CONFIG_TINYUSB_MSC_ENABLED

MSC Mount Path of storage.

Default value:

Communication Device Class (CDC)

Contains:

CONFIG_TINYUSB_CDC_ENABLED

Enable TinyUSB CDC feature

Found in: TinyUSB Stack > Communication Device Class (CDC)

Enable TinyUSB CDC feature.

Default value:

  • No (disabled)

CONFIG_TINYUSB_CDC_COUNT

CDC Channel Count

Found in: TinyUSB Stack > Communication Device Class (CDC) > CONFIG_TINYUSB_CDC_ENABLED

Number of independent serial ports.

Range:
Default value:
CONFIG_TINYUSB_CDC_RX_BUFSIZE

CDC FIFO size of RX channel

Found in: TinyUSB Stack > Communication Device Class (CDC) > CONFIG_TINYUSB_CDC_ENABLED

This buffer size defines maximum data length in bytes that you can receive at once. Must be greater or equal to TINYUSB_CDC_EP_BUFSIZE for correct receiving.

Range:
Default value:
CONFIG_TINYUSB_CDC_TX_BUFSIZE

CDC FIFO size of TX channel

Found in: TinyUSB Stack > Communication Device Class (CDC) > CONFIG_TINYUSB_CDC_ENABLED

This buffer size defines maximum data length in bytes that you can transmit at once.

Default value:
CONFIG_TINYUSB_CDC_EP_BUFSIZE

CDC Endpoint buffer size

Found in: TinyUSB Stack > Communication Device Class (CDC) > CONFIG_TINYUSB_CDC_ENABLED

This low layer buffer has the most significant impact on performance. Set to 8192 for best performance. Sizes above 8192 bytes bring only little performance improvement.

Default value:

Musical Instrument Digital Interface (MIDI)

Contains:

CONFIG_TINYUSB_MIDI_COUNT

TinyUSB MIDI interfaces count

Found in: TinyUSB Stack > Musical Instrument Digital Interface (MIDI)

Setting value greater than 0 will enable TinyUSB MIDI feature.

Range:

  • from 0 to 2

Default value:

  • 0

Human Interface Device Class (HID)

Contains:

CONFIG_TINYUSB_HID_COUNT

TinyUSB HID interfaces count

Found in: TinyUSB Stack > Human Interface Device Class (HID)

Setting value greater than 0 will enable TinyUSB HID feature.

Range:

  • from 0 to 4

Default value:

  • 0

Device Firmware Upgrade (DFU)

Contains:

CONFIG_TINYUSB_DFU_MODE

DFU mode

Found in: TinyUSB Stack > Device Firmware Upgrade (DFU)

Select which DFU driver you want to use.

Available options:

  • DFU (CONFIG_TINYUSB_DFU_MODE_DFU)

  • DFU Runtime (CONFIG_TINYUSB_DFU_MODE_DFU_RUNTIME)

  • None (CONFIG_TINYUSB_DFU_MODE_NONE)

CONFIG_TINYUSB_DFU_BUFSIZE

DFU XFER BUFFSIZE

Found in: TinyUSB Stack > Device Firmware Upgrade (DFU)

DFU XFER BUFFSIZE.

Default value:

Bluetooth Host Class (BTH)

Contains:

CONFIG_TINYUSB_BTH_ENABLED

Enable TinyUSB BTH feature

Found in: TinyUSB Stack > Bluetooth Host Class (BTH)

Enable TinyUSB BTH feature.

Default value:

  • No (disabled)

CONFIG_TINYUSB_BTH_ISO_ALT_COUNT

BTH ISO ALT COUNT

Found in: TinyUSB Stack > Bluetooth Host Class (BTH) > CONFIG_TINYUSB_BTH_ENABLED

BTH ISO ALT COUNT.

Default value:

Network driver (ECM/NCM/RNDIS)

Contains:

CONFIG_TINYUSB_NET_MODE

Network mode

Found in: TinyUSB Stack > Network driver (ECM/NCM/RNDIS)

Select network driver you want to use.

Available options:

  • ECM/RNDIS (CONFIG_TINYUSB_NET_MODE_ECM_RNDIS)

  • NCM (CONFIG_TINYUSB_NET_MODE_NCM)

  • None (CONFIG_TINYUSB_NET_MODE_NONE)

CONFIG_TINYUSB_NCM_OUT_NTB_BUFFS_COUNT

Number of NCM NTB buffers for reception side

Found in: TinyUSB Stack > Network driver (ECM/NCM/RNDIS)

Number of NTB buffers for reception side. Can be increased to improve performance and stability with the cost of additional RAM requirements. Helps to mitigate “tud_network_can_xmit: request blocked” warning message when running NCM device.

Range:
Default value:

CONFIG_TINYUSB_NCM_IN_NTB_BUFFS_COUNT

Number of NCM NTB buffers for transmission side

Found in: TinyUSB Stack > Network driver (ECM/NCM/RNDIS)

Number of NTB buffers for transmission side. Can be increased to improve performance and stability with the cost of additional RAM requirements. Helps to mitigate “tud_network_can_xmit: request blocked” warning message when running NCM device.

Range:
Default value:

CONFIG_TINYUSB_NCM_OUT_NTB_BUFF_MAX_SIZE

NCM NTB Buffer size for reception size

Found in: TinyUSB Stack > Network driver (ECM/NCM/RNDIS)

Size of NTB buffers on the reception side. The minimum size used by Linux is 2048 bytes. NTB buffer size must be significantly larger than the MTU (Maximum Transmission Unit). The typical default MTU size for Ethernet is 1500 bytes, plus an additional packet overhead. To improve performance, the NTB buffer size should be large enough to fit multiple MTU-sized frames in a single NTB buffer and it’s length should be multiple of 4.

Range:
Default value:

CONFIG_TINYUSB_NCM_IN_NTB_BUFF_MAX_SIZE

NCM NTB Buffer size for transmission size

Found in: TinyUSB Stack > Network driver (ECM/NCM/RNDIS)

Size of NTB buffers on the transmission side. The minimum size used by Linux is 2048 bytes. NTB buffer size must be significantly larger than the MTU (Maximum Transmission Unit). The typical default MTU size for Ethernet is 1500 bytes, plus an additional packet overhead. To improve performance, the NTB buffer size should be large enough to fit multiple MTU-sized frames in a single NTB buffer and it’s length should be multiple of 4.

Range:
Default value:

Vendor Specific Interface

Contains:

CONFIG_TINYUSB_VENDOR_COUNT

TinyUSB Vendor specific interfaces count

Found in: TinyUSB Stack > Vendor Specific Interface

Setting value greater than 0 will enable TinyUSB Vendor specific feature.

Range:

  • from 0 to 2

Default value:

  • 0

CONFIG_TINYUSB_VENDOR_RX_BUFSIZE

Vendor specific FIFO size of RX channel

Found in: TinyUSB Stack > Vendor Specific Interface

This buffer size defines maximum data length in bytes that you can receive at once.

Note: Unlike other USB classes, the vendor class supports setting buffer sizes to 0 to disable internal buffering. When disabled, RX data goes directly to tud_vendor_rx_cb(), the tud_vendor_read() function is not available and application must handle data in the callback.

Range:
Default value:

CONFIG_TINYUSB_VENDOR_TX_BUFSIZE

Vendor specific FIFO size of TX channel

Found in: TinyUSB Stack > Vendor Specific Interface

This buffer size defines maximum data length in bytes that you can transmit at once.

Note: Unlike other USB classes, the vendor class supports setting buffer sizes to 0 to disable internal buffering. When disabled, tud_vendor_write() bypasses internal software FIFO.

Range:
Default value:

CONFIG_TINYUSB_VENDOR_EPSIZE

Vendor specific Endpoint buffer size

Found in: TinyUSB Stack > Vendor Specific Interface

This low layer buffer has the most significant impact on performance. Set to 8192 for best performance. Sizes above 8192 bytes bring only little performance improvement.

Range:
Default value: