USB Device Driver

Overview

The driver allows users to use ESP32-S3 chips to develop USB devices on top the TinyUSB stack. TinyUSB is integrating with ESP-IDF to provide USB features of the framework. Using this driver the chip works as a composite device supporting to represent several USB devices simultaneously. Currently, only the communications device class (CDC) type of the device with the ACM (Abstract Control Model) subclass is supported.

Features

Configuration of device and string USB descriptors
USB Serial Device (CDC-ACM)
Input and output through USB Serial Device

Hardware USB Connection

Any board with the ESP32-S3 chip with USB connectors or with exposed USB’s D+ and D- (DATA+/DATA-) pins.

If the board has no USB connector but has the pins, connect pins directly to the host (e.g. with do-it-yourself cable from any USB connection cable).

On ESP32-S3, connect GPIO 20 and 19 to D+/D- respectively:

Connection of a board to a host ESP chip

Driver Structure

As the basis is used the TinyUSB stack.

On top of it the driver implements:

Customization of USB descriptors
Serial device support
Redirecting of standard streams through the Serial device
Encapsulated driver’s task servicing the TinyuSB

Configuration

Via Menuconfig options you can specify:

Several of descriptor’s parameters (see: Descriptors Configuration bellow)
USB Serial low-level Configuration
The verbosity of the TinyUSB’s log
Disable the TinyUSB main task (for the custom implementation)

Descriptors Configuration

The driver’s descriptors are provided by the tinyusb_config_t structure’s descriptor and string_descriptor members. Therefore, users should initialize tinyusb_config_t to their desired descriptor before calling tinyusb_driver_install() to install driver.

However, the driver also provides a default descriptor. The driver can be installed with the default descriptor by setting the descriptor and string_descriptor members of tinyusb_config_t to NULL before calling tinyusb_driver_install(). The driver’s default descriptor is specified using Menuconfig, where the following fields should be configured:

PID
VID
bcdDevice
Manufacturer
Product name
Name of CDC device if it is On
Serial number

If you want to use own descriptors with extended modification, you can define them during the driver installation process

Install Driver

To initialize the driver, users should call tinyusb_driver_install(). The driver’s configuration is specified in a tinyusb_config_t structure that is passed as an argument to tinyusb_driver_install().

Note that the tinyusb_config_t structure can be zero initialized (e.g. tinyusb_config_t tusb_cfg = { 0 }) or partially (as shown below). For any member that is initialized to 0 or NULL, the driver will use its default configuration values for that member (see example below)

tinyusb_config_t partial_init = {
    .descriptor = NULL;         //Uses default descriptor specified in Menuconfig
    .string_descriptor = NULL;  //Uses default string specified in Menuconfig
    .external_phy = false;
}

USB Serial Device (CDC-ACM)

If the CDC option is enabled in Menuconfig, the USB Serial Device could be initialized with tusb_cdc_acm_init() according to the settings from tinyusb_config_cdcacm_t (see example below).

tinyusb_config_cdcacm_t amc_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(&amc_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 driver allows to redirect all standard application strings (stdin/out/err) to the USB Serial Device and return them to UART using esp_tusb_init_console()/esp_tusb_deinit_console() functions.

Application Examples

The table below describes the code examples available in the directory peripherals/usb/.

Code Example	Description
peripherals/usb/tusb_console	How to set up ESP32-S3 chip to get log output via Serial Device connection
peripherals/usb/tusb_sample_descriptor	How to set up ESP32-S3 chip to work as a Generic USB Device with a user-defined descriptor
peripherals/usb/tusb_serial_device	How to set up ESP32-S3 chip to work as a USB Serial Device

API Reference

Header File

components/tinyusb/additions/include/tinyusb.h

Functions

esp_err_t tinyusb_driver_install(const tinyusb_config_t *config)

This is an all-in-one helper function, including:

USB device driver initialization
Descriptors preparation
TinyUSB stack initialization
Creates and start a task to handle usb events

Note

Don’t change Custom descriptor, but if it has to be done, Suggest to define as follows in order to match the Interface Association Descriptor (IAD): bDeviceClass = TUSB_CLASS_MISC, bDeviceSubClass = MISC_SUBCLASS_COMMON,

Parameters

config – tinyusb stack specific configuration

Return values

ESP_ERR_INVALID_ARG – Install driver and tinyusb stack failed because of invalid argument
ESP_FAIL – Install driver and tinyusb stack failed because of internal error
ESP_OK – Install driver and tinyusb stack successfully

Structures

struct tinyusb_config_t

Configuration structure of the tinyUSB core.

Public Members

tusb_desc_device_t *descriptor: Pointer to a device descriptor

const char **string_descriptor: Pointer to an array of string descriptors

bool external_phy: Should USB use an external PHY

Header File

components/tinyusb/additions/include/tinyusb_types.h

Macros

USB_ESPRESSIF_VID

USB_STRING_DESCRIPTOR_ARRAY_SIZE

Type Definitions

typedef const char *tusb_desc_strarray_device_t[7]

Enumerations

enum tinyusb_usbdev_t

Values:

enumerator TINYUSB_USBDEV_0

Header File

components/tinyusb/additions/include/tusb_cdc_acm.h

Functions

esp_err_t tusb_cdc_acm_init(const tinyusb_config_cdcacm_t *cfg)

Initialize CDC ACM. Initialization will be finished with the tud_cdc_line_state_cb callback.

Parameters: cfg – - init configuration structure
Returns: esp_err_t

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 callback invoking on CDC event. If the callback had been already registered, it will be overwritten.

Parameters

itf – - number of a CDC object
event_type – - type of registered event for a callback
callback – - callback function

Returns

esp_err_t - ESP_OK or ESP_ERR_INVALID_ARG

esp_err_t tinyusb_cdcacm_unregister_callback(tinyusb_cdcacm_itf_t itf, cdcacm_event_type_t event_type)

Unregister a callback invoking on CDC event.

Parameters

itf – - number of a CDC object
event_type – - type of registered event for a callback

Returns

esp_err_t - ESP_OK or ESP_ERR_INVALID_ARG

size_t tinyusb_cdcacm_write_queue_char(tinyusb_cdcacm_itf_t itf, char ch)

Sent one character to a write buffer.

Parameters

itf – - number of a CDC object
ch – - character to send

Returns

size_t - amount of queued bytes

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

Write data to write buffer from a byte array.

Parameters

itf – - number of a CDC object
in_buf – - a source array
in_size – - size to write from arr_src

Returns

size_t - amount of queued bytes

esp_err_t tinyusb_cdcacm_write_flush(tinyusb_cdcacm_itf_t itf, uint32_t timeout_ticks)

Send all data from a write buffer. Use tinyusb_cdcacm_write_queue to add data to the buffer.

WARNING! TinyUSB can block output Endpoint for several RX callbacks, after will do additional flush after the each trasfer. That can leads to the situation when you requested a flush, but it will fail until ont of the next callbacks ends. SO USING OF THE FLUSH WITH TIMEOUTS IN CALLBACKS IS NOT RECOMENDED - YOU CAN GET A LOCK FOR THE TIMEOUT

Parameters

itf – - number of a CDC object
timeout_ticks – - waiting until flush will be considered as failed

Returns

esp_err_t - ESP_OK if (timeout_ticks > 0) and and flush was successful, ESP_ERR_TIMEOUT if timeout occurred3 or flush was successful with (timeout_ticks == 0) ESP_FAIL if flush was unsuccessful

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 a content to the array, and defines it’s size to the sz_store.

Parameters

itf – - number of a CDC object
out_buf – - to this array will be stored the object from a CDC buffer
out_buf_sz – - size of buffer for results
rx_data_size – - to this address will be stored the object’s size

Returns

esp_err_t ESP_OK, ESP_FAIL or ESP_ERR_INVALID_STATE

bool tusb_cdc_acm_initialized(tinyusb_cdcacm_itf_t itf)

Check if the ACM initialized.

Parameters: itf – - number of a CDC object
Returns: true or false

Structures

struct cdcacm_event_rx_wanted_char_data_t

Data provided to the input of the callback_rx_wanted_char callback.

Public Members

char wanted_char: Wanted character

struct cdcacm_event_line_state_changed_data_t

Data provided to the input of the callback_line_state_changed callback.

Public Members

bool dtr: Data Terminal Ready (DTR) line state

bool rts: Request To Send (RTS) line state

struct cdcacm_event_line_coding_changed_data_t

Data provided to the input of the line_coding_changed callback.

Public Members

cdc_line_coding_t const *p_line_coding: New line coding value

struct cdcacm_event_t

Describes an event passing to the input of a callbacks.

Public Members

cdcacm_event_type_t type: Event type

cdcacm_event_rx_wanted_char_data_t rx_wanted_char_data: Data input of the callback_rx_wanted_char callback

cdcacm_event_line_state_changed_data_t line_state_changed_data: Data input of the callback_line_state_changed callback

cdcacm_event_line_coding_changed_data_t line_coding_changed_data: Data input of the line_coding_changed callback

struct tinyusb_config_cdcacm_t

Configuration structure for CDC-ACM.

Public Members

tinyusb_usbdev_t usb_dev: Usb device to set up

tinyusb_cdcacm_itf_t cdc_port: CDC port

size_t rx_unread_buf_sz: Amount of data that can be passed to the AMC at once

tusb_cdcacm_callback_t callback_rx: Pointer to the function with the tusb_cdcacm_callback_t type that will be handled as a callback

tusb_cdcacm_callback_t callback_rx_wanted_char: Pointer to the function with the tusb_cdcacm_callback_t type that will be handled as a callback

tusb_cdcacm_callback_t callback_line_state_changed: Pointer to the function with the tusb_cdcacm_callback_t type that will be handled as a callback

tusb_cdcacm_callback_t callback_line_coding_changed: Pointer to the function with the tusb_cdcacm_callback_t type that will be handled as a callback

Type Definitions

typedef void (*tusb_cdcacm_callback_t)(int itf, cdcacm_event_t *event): CDC-ACM callback type.

Enumerations

enum tinyusb_cdcacm_itf_t

CDC ports available to setup.

Values:

enumerator TINYUSB_CDC_ACM_0

enum cdcacm_event_type_t

Types of CDC ACM events.

Values:

enumerator CDC_EVENT_RX

enumerator CDC_EVENT_RX_WANTED_CHAR

enumerator CDC_EVENT_LINE_STATE_CHANGED

enumerator CDC_EVENT_LINE_CODING_CHANGED

Header File

components/tinyusb/additions/include/tusb_console.h

Functions

esp_err_t esp_tusb_init_console(int cdc_intf)

Redirect output to the USB serial.

Parameters: cdc_intf – - interface number of TinyUSB’s CDC
Returns: esp_err_t - ESP_OK, ESP_FAIL or an error code

esp_err_t esp_tusb_deinit_console(int cdc_intf)

Switch log to the default output.

Parameters: cdc_intf – - interface number of TinyUSB’s CDC
Returns: esp_err_t

Header File

components/tinyusb/additions/include/tusb_tasks.h

Functions

esp_err_t tusb_run_task(void)

This helper function creates and starts a task which wraps tud_task().

The wrapper function basically wraps tud_task and some log. Default parameters: stack size and priority as configured, argument = NULL, not pinned to any core. If you have more requirements for this task, you can create your own task which calls tud_task as the last step.

Return values

ESP_OK – run tinyusb main task successfully
ESP_FAIL – run tinyusb main task failed of internal error
ESP_ERR_INVALID_STATE – tinyusb main task has been created before

esp_err_t tusb_stop_task(void)

This helper function stops and destroys the task created by tusb_run_task()

Return values

ESP_OK – stop and destory tinyusb main task successfully
ESP_ERR_INVALID_STATE – tinyusb main task hasn’t been created yet

Header File

components/tinyusb/additions/include/vfs_tinyusb.h

Functions

esp_err_t esp_vfs_tusb_cdc_register(int cdc_intf, char const *path)

Register TinyUSB CDC at VFS with path.

Parameters

cdc_intf – - interface number of TinyUSB’s CDC
path – - path where the CDC will be registered, /dev/tusb_cdc will be used if left NULL.

Returns

esp_err_t ESP_OK or ESP_FAIL

esp_err_t esp_vfs_tusb_cdc_unregister(char const *path)

Unregister TinyUSB CDC from VFS.

Parameters: path – - path where the CDC will be unregistered if NULL will be used /dev/tusb_cdc
Returns: esp_err_t ESP_OK or ESP_FAIL

Provide feedback about this document