Chapter 147: USB Implementation in ESP32 Series

Chapter Objectives

Upon completing this chapter, you will be able to:

• Understand fundamental USB concepts: Host, Device, Endpoints, Transfers, and Descriptors.
• Identify ESP32 variants that support native USB device functionality (USB OTG or dedicated USB Device Interface).
• Differentiate between native USB device capabilities and USB-to-UART bridge chips.
• Understand the role of the TinyUSB stack within the ESP-IDF for USB device implementation.
• Configure and implement a USB Communication Device Class (CDC) device, creating a virtual COM port.
• Build, flash, and test USB CDC applications on compatible ESP32 variants.
• Recognize common issues and apply troubleshooting techniques for USB device development.
• Distinguish the capabilities of the USB Serial/JTAG controller found on some variants from full USB device interfaces.

Introduction

The Universal Serial Bus (USB) is a cornerstone of modern computing, providing a standardized interface for connecting a vast array of peripherals to computers and other host devices. Its plug-and-play nature, combined with its ability to supply power, has made it incredibly versatile. For embedded systems like those built around the ESP32, USB connectivity opens up numerous possibilities, including:

• Data Logging: Streaming sensor data directly to a PC for analysis and storage.
• Device Configuration: Providing a command-line interface or custom protocol over USB for device setup.
• Firmware Updates: Implementing custom USB bootloaders or update mechanisms.
• Custom Peripherals: Creating bespoke USB devices like Human Interface Devices (HIDs), Mass Storage Devices (MSCs), or specialized data acquisition tools.
• Debugging: Offering an alternative or supplementary channel for debug information beyond traditional UART.

While many ESP32 development boards include a USB-to-UART bridge chip (e.g., CP210x, CH340) for programming and serial communication, some ESP32 variants, notably the ESP32-S2, ESP32-S3, and ESP32-C6, feature a built-in USB peripheral. This native USB capability allows the ESP32 itself to act as a USB device, offering greater flexibility and performance. This chapter focuses on harnessing this native USB functionality using the ESP-IDF and its integrated TinyUSB stack.

Theory

USB Fundamentals

USB is a host-controlled bus. This means there is a single USB Host (typically a PC) that manages the bus and initiates all communication, and one or more USB Devices (peripherals like a mouse, keyboard, or an ESP32 acting as a device) that respond to the host’s requests.

Key USB Concepts:

USB Descriptors

When a USB device is connected to a host, the host queries the device for information about its capabilities. This information is provided in a structured format through descriptors. Descriptors are blocks of data that describe the device and its interfaces.

graph TD
    A[Device Descriptor<br><span style='font-size:smaller; color:#374151;'>VID, PID, USB Ver,<br>Num Configurations</span>] --> B{Configuration Descriptor 1<br><span style='font-size:smaller; color:#374151;'>Power Req, Num Interfaces</span>};
    A --> C(...);
    A --> D{Configuration Descriptor N};

    subgraph Config 1 Details
        B --> E{"Interface Descriptor 0 (e.g., CDC Control)<br><span style='font-size:smaller; color:#374151;'>Class, SubClass, Protocol,<br>Num Endpoints</span>"};
        B --> F{"Interface Descriptor 1 (e.g., CDC Data)<br><span style='font-size:smaller; color:#374151;'>Class, SubClass, Protocol,<br>Num Endpoints</span>"};
    end
    
    subgraph Interface 0 Endpoints
        E --> G["Endpoint Descriptor (EP0 IN/OUT - Control)<br><span style='font-size:smaller; color:#374151;'>Type: Control, MaxPacketSize</span>"];
        E --> H["Endpoint Descriptor (e.g., EP1 IN - CDC Notify)<br><span style='font-size:smaller; color:#374151;'>Type: Interrupt, MaxPacketSize, Interval</span>"];
    end

    subgraph Interface 1 Endpoints
        F --> I["Endpoint Descriptor (e.g., EP2 OUT - CDC Data OUT)<br><span style='font-size:smaller; color:#374151;'>Type: Bulk, MaxPacketSize</span>"];
        F --> J["Endpoint Descriptor (e.g., EP3 IN - CDC Data IN)<br><span style='font-size:smaller; color:#374151;'>Type: Bulk, MaxPacketSize</span>"];
    end

    A -.-> K["String Descriptors<br><span style='font-size:smaller; color:#374151;'>(Optional: Manufacturer, Product, Serial Number)</span>"];
    B -.-> K;
    E -.-> K;


    classDef root fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
    classDef config fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef interface fill:#D1FAE5,stroke:#059669,stroke-width:1px,color:#065F46;
    classDef endpoint fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;
    classDef string fill:#FEE2E2,stroke:#DC2626,stroke-width:1px,color:#991B1B;

    class A root;
    class B,C,D config;
    class E,F interface;
    class G,H,I,J endpoint;
    class K string;

USB Device Classes

To simplify driver development on the host side, USB defines standard Device Classes. A device class specifies a common set of functionalities and a standard way for the host to interact with devices belonging to that class. Common classes include:

By adhering to a standard device class, an ESP32-based USB device can often use generic drivers already present on the host operating system, simplifying deployment.

ESP-IDF USB Stack: TinyUSB

The ESP-IDF utilizes TinyUSB as its underlying USB device stack for ESP32 variants with native USB capabilities (ESP32-S2, ESP32-S3, ESP32-C6’s USB 2.0 Device Interface). TinyUSB is an open-source, cross-platform USB host and device stack designed for microcontrollers. It’s known for its small memory footprint and ease of use.

Key features of TinyUSB relevant to ESP-IDF:

• Supports multiple device classes (CDC, MSC, HID, MIDI, etc.).
• Handles low-level USB protocol details.
• Provides a higher-level API for application developers to interact with USB functionality.
• Integrated into ESP-IDF, making it straightforward to include in projects.

When you configure your ESP32 project for USB functionality (e.g., CDC), ESP-IDF components will initialize and manage the TinyUSB stack, which in turn interacts with the USB hardware peripheral on the chip.

graph LR
    subgraph Host PC
        direction LR
        App_PC["PC Application<br>(e.g., Serial Terminal, Game)"] --> HostDriver["OS USB Driver<br>(e.g., CDC, HID Driver)"];
        HostDriver --> HostController[PC USB Host Controller Hardware];
    end

    subgraph ESP32 Device
        direction RL
        App_ESP32["ESP32 Application Logic<br>(e.g., CDC Echo, Sensor Read)"] --> TinyUSB_API["TinyUSB API<br><span style='font-size:smaller; color:#374151;'>(tud_cdc_..., tud_hid_...</span>"];
        TinyUSB_API --> TinyUSB_Core["TinyUSB Core Stack<br><span style='font-size:smaller; color:#374151;'>(Protocol, Descriptors, Class Drivers)</span>"];
        TinyUSB_Core --> ESP_IDF_USB_HAL[ESP-IDF USB HAL /<br>Low-Level Driver];
        ESP_IDF_USB_HAL --> ESP32_USB_HW["ESP32 Native USB<br>Peripheral Hardware<br>(S2/S3 OTG, C6 USB Device IF)"];
    end
    
    HostController -. USB Cable .-> ESP32_USB_HW;

    classDef host fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef esp_app fill:#D1FAE5,stroke:#059669,stroke-width:1px,color:#065F46;
    classDef tinyusb fill:#EDE9FE,stroke:#5B21B6,stroke-width:1.5px,color:#5B21B6;
    classDef hal_hw fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;

    class App_PC,HostDriver,HostController host;
    class App_ESP32 esp_app;
    class TinyUSB_API,TinyUSB_Core tinyusb;
    class ESP_IDF_USB_HAL,ESP32_USB_HW hal_hw;

Practical Examples

The primary focus of these examples will be on the ESP32-S2, ESP32-S3, and ESP32-C6 (using its dedicated USB 2.0 Device Interface) as these have the necessary hardware for full USB device functionality with TinyUSB.

Prerequisites:

• ESP-IDF v5.x installed and configured with VS Code.
• An ESP32-S2, ESP32-S3, or ESP32-C6 development board with its native USB D+/D- pins accessible (often connected to a dedicated USB connector, distinct from a USB-to-UART bridge connector if present).
• A USB cable to connect the ESP32’s native USB port to your PC.

Example 1: USB CDC (Virtual COM Port) Echo

This example configures the ESP32 as a USB CDC device. When connected to a PC, it will appear as a new serial (COM) port. Any data sent from the PC to this COM port will be echoed back by the ESP32.

sequenceDiagram
    participant PC as Host PC (Serial Terminal)
    participant ESP32 as ESP32 (TinyUSB CDC Device)
    
    rect rgb(230, 240, 255)
    Note over ESP32: Initialization Phase
    ESP32->>ESP32: tinyusb_driver_install(&tusb_cfg)
    Note over ESP32: TinyUSB stack starts, USB enumeration occurs with Host
    end

    PC->>ESP32: User types "Hello" in terminal (Data Sent)
    Note over ESP32: tud_cdc_rx_cb(itf) invoked
    ESP32->>ESP32: tud_cdc_n_read(itf, buf, size)
    ESP32->>ESP32: tud_cdc_n_write(itf, buf, count) (Echo back)
    ESP32->>ESP32: tud_cdc_n_write_flush(itf)
    ESP32-->>PC: "Hello" (Data Received by Terminal)

    Note over PC, ESP32: Process repeats for further data

    rect rgb(255, 240, 230)
    Note over ESP32: Optional: Line State Changes
    PC->>ESP32: Terminal Opens/Closes (DTR/RTS change)
    Note over ESP32: tud_cdc_line_state_cb(itf, dtr, rts) invoked
    ESP32->>ESP32: Log DTR/RTS state
    end

1. Project Configuration (menuconfig):

1. Open your ESP-IDF project in VS Code.
2. Run idf.py menuconfig (or use the VS Code ESP-IDF Extension: SDK Configuration Editor).
3. Navigate to Component config —> TinyUSB Stack.
   • Ensure Enable TinyUSB Stack is checked ([*]).
   • Under CDC Interface, select Enable CDC Interface ([*]).
   • You can leave other CDC settings (like Number of CDC interfaces) at their defaults for this example.
4. Save the configuration and exit menuconfig.

2. Code (main/usb_cdc_echo_main.c):

#include <stdio.h>
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "tinyusb.h"
#include "tusb_cdc_acm.h"

static const char *TAG = "USB_CDC_Echo";

#define TUSB_DESC_TOTAL_LEN (TUD_CONFIG_DESC_LEN + TUD_CDC_DESC_LEN)

// USB Descriptors
static const uint8_t desc_configuration[] = {
    // Config number, interface count, string index, total length, attribute, power in mA
    TUD_CONFIG_DESCRIPTOR(1, ITF_NUM_TOTAL, 0, TUSB_DESC_TOTAL_LEN, TUSB_DESC_CONFIG_ATT_REMOTE_WAKEUP, 100),
    // Interface number, string index, EP notification address and size, EP data address (out, in) and size.
    TUD_CDC_DESCRIPTOR(ITF_NUM_CDC, 0, EPNUM_CDC_NOTIF, 8, EPNUM_CDC_OUT, EPNUM_CDC_IN, TUD_CDC_EP_BUFSIZE),
};

// Invoked when received new data
void tud_cdc_rx_cb(uint8_t itf)
{
    char buf[64];
    uint32_t count = tud_cdc_n_read(itf, buf, sizeof(buf));
    if (count > 0) {
        ESP_LOGI(TAG, "Received %lu bytes from USB CDC", count);
        // Echo back
        tud_cdc_n_write(itf, buf, count);
        tud_cdc_n_write_flush(itf);
        ESP_LOGI(TAG, "Echoed %lu bytes", count);
    }
}

// Invoked when CDC interface is mounted
void tud_cdc_line_state_cb(uint8_t itf, bool dtr, bool rts)
{
    ESP_LOGI(TAG, "CDC line state changed: DTR: %d, RTS: %d", dtr, rts);
    // You can use dtr to detect if a host terminal is connected.
}

void app_main(void)
{
    ESP_LOGI(TAG, "Initializing TinyUSB for CDC Echo");

    // Configure TinyUSB driver
    tinyusb_config_t tusb_cfg = {
        .device_descriptor = NULL, // Use default TinyUSB device descriptor
        .string_descriptor = NULL, // Use default TinyUSB string descriptors
        .external_phy = false,     // For ESP32-S2/S3/C6 internal PHY
        .configuration_descriptor = desc_configuration,
    };

    ESP_ERROR_CHECK(tinyusb_driver_install(&tusb_cfg));
    ESP_LOGI(TAG, "TinyUSB driver installed.");

    // The main loop for this example doesn't need to do much,
    // as TinyUSB callbacks handle the USB events in their own context.
    while (1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

3. CMakeLists.txt (in main directory):

Ensure your CMakeLists.txt includes necessary components. ESP-IDF’s build system will automatically link TinyUSB if it’s enabled in menuconfig.

idf_component_register(SRCS "usb_cdc_echo_main.c"
                    INCLUDE_DIRS ".")

4. Build Instructions:

1. Open VS Code.
2. Ensure your ESP-IDF environment is sourced.
3. Select your target ESP32 variant (e.g., esp32s2, esp32s3, esp32c6).
4. Build the project (Espressif IDF: Build Project).

5. Run/Flash/Observe Steps:

1. Connect your ESP32 board’s native USB port to your computer.
   • For some ESP32-S2/S3 boards, this might be the same port used for programming if it’s a native USB-capable board. For others, it might be a separate “USB OTG” or “USB” connector.
   • For ESP32-C6, ensure you are connecting to the port associated with the dedicated USB 2.0 Device Interface (D+/D- pins), not necessarily the USB Serial/JTAG port if they are separate.
2. Flash the project (Espressif IDF: Flash Device). You might need to put the ESP32 into bootloader mode manually if flashing via the native USB port for the first time or if the USB CDC isn’t active yet.
3. Once flashed and running, your PC should detect a new USB device and, after a moment, enumerate it as a virtual COM port.
   • Windows: Check Device Manager under “Ports (COM & LPT)”.
   • Linux: Check dmesg for detection and look for a /dev/ttyACMx device.
   • macOS: Look for a /dev/cu.usbmodemXXXX device.
4. Open a serial terminal program (e.g., PuTTY, Tera Term, minicom, CoolTerm) and connect to this new COM port. Baud rate settings usually don’t matter for USB CDC, but you can set one (e.g., 115200).
5. Type some characters in the terminal and press Enter. The ESP32 should echo them back to your terminal.
6. You can also observe the ESP_LOGI messages via your standard ESP-IDF Monitor (which might be connected via a separate USB-to-UART bridge or the USB Serial/JTAG port, depending on your board and setup).

Tip: If your board has both a USB-to-UART bridge (for programming/UART0) and a native USB connector, ensure you connect the correct USB port for this example (the native one).

Variant Notes

Understanding which ESP32 variant supports which type of USB functionality is crucial.

• ESP32 (Original):
  • No native USB device peripheral. Most ESP32 development boards use an external USB-to-UART bridge chip (e.g., CP210x, CH340) that connects to the ESP32’s UART pins. This chip handles the USB communication with the PC and appears as a COM port. The ESP32 itself is only doing UART communication.
  • Not suitable for the TinyUSB device examples in this chapter.
• ESP32-S2:
  • USB OTG (On-The-Go) peripheral (Full Speed – 12 Mbps). Can act as a USB device or a limited USB host.
  • Excellent candidate for TinyUSB device examples (CDC, MSC, HID, etc.).
  • The USB OTG pins (GPIO19 for D-, GPIO20 for D+) are used.
• ESP32-S3:
  • USB OTG peripheral (Full Speed – 12 Mbps). Similar to ESP32-S2.
  • Excellent candidate for TinyUSB device examples.
  • The USB OTG pins (GPIO19 for D-, GPIO20 for D+) are used.
• ESP32-C3:
  • USB Serial/JTAG Controller. This peripheral provides serial communication (console output, flashing) and JTAG debugging over USB. It can appear as a CDC-like device for serial data.
  • It is NOT a full USB OTG peripheral and is not typically used with the full TinyUSB stack for arbitrary device classes like MSC or custom HID in the same way as S2/S3. While it provides serial over USB, its primary purpose is console/JTAG. ESP-IDF has built-in support for this without needing explicit TinyUSB CDC configuration by the user for basic console.
  • The CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG option in menuconfig enables the serial console over this interface.
• ESP32-C6:
  • Has two distinct USB capabilities:
    1. USB Serial/JTAG Controller: Similar to ESP32-C3, for console and JTAG.
    2. USB 2.0 Device Interface (Full Speed – 12 Mbps): This is a separate, full-fledged USB device peripheral that can be used with TinyUSB to implement standard device classes like CDC, MSC, HID, etc. This is the interface targeted by the TinyUSB examples.
  • Excellent candidate for TinyUSB device examples when using its dedicated USB 2.0 Device Interface pins. Ensure your development board wires these pins (typically GPIO12 for D-, GPIO13 for D+ on many reference designs, but check your board’s schematic) to a USB connector.
• ESP32-H2:
  • USB Serial/JTAG Controller: Similar to ESP32-C3, for console and JTAG.
  • Like the C3, not typically used with the full TinyUSB stack for implementing diverse device classes via this specific port.

Summary for TinyUSB Device Implementation:

• Use ESP32-S2, ESP32-S3, or ESP32-C6 (its USB 2.0 Device Interface).
• The original ESP32 is not suitable.
• ESP32-C3 and ESP32-H2’s USB Serial/JTAG port serves a different primary purpose (console/debug), though it does provide serial over USB.

Common Mistakes & Troubleshooting Tips

Exercises

1. USB CDC Sensor Data Streamer:
   • Objective: Modify the CDC Echo example to read data from a sensor (e.g., the built-in temperature sensor on some ESP32s, or an external ADC/I2C sensor) and send it periodically to the PC over USB CDC.
   • Steps:
     1. Initialize the chosen sensor (refer to relevant chapters, e.g., Chapter 126 for ADC, or internal temperature sensor APIs).
     2. In a FreeRTOS task, read the sensor value every 1-2 seconds.
     3. Format the sensor value into a string (e.g., “Temperature: XX.X C\n”).
     4. Use tud_cdc_n_write() to send this string to the connected PC.
     5. Observe the data stream in a serial terminal on the PC.
2. USB CDC Command Controlled LED:
   • Objective: Control an onboard LED by sending commands from the PC via USB CDC.
   • Steps:
     1. Configure a GPIO pin connected to an LED as an output.
     2. In the tud_cdc_rx_cb() callback:
        • Read the received data.
        • Implement a simple command parser (e.g., “LED_ON”, “LED_OFF”).
        • If “LED_ON” is received, turn the LED on.
        • If “LED_OFF” is received, turn the LED off.
        • Optionally, send an acknowledgment back to the PC (e.g., “ACK: LED is ON”).
     3. Test by sending commands from a serial terminal.
3. Research: Basic USB HID Mouse (Conceptual for ESP32-S2/S3/C6):
   • Objective: Understand the key components needed to implement a very basic USB HID mouse that can move the PC’s cursor slightly. This is a research and design exercise, not full implementation.
   • Tasks:
     1. Consult the TinyUSB documentation and examples for HID mouse.
     2. Identify the structure of a HID Report Descriptor for a simple mouse (e.g., X, Y movement, buttons).
     3. Outline the main functions/callbacks you would need to implement (e.g., tud_hid_report_complete_cb, how to send a mouse report).
     4. What data would you send in a mouse report to move the cursor, for example, 10 pixels to the right?
     5. In menuconfig, what settings under TinyUSB Stack -> HID Interface would be relevant?

Summary

• Native USB device functionality is available on ESP32-S2, ESP32-S3 (USB OTG), and ESP32-C6 (USB 2.0 Device Interface), enabling them to act as various USB peripherals.
• The original ESP32 lacks native USB device capabilities; it relies on external USB-to-UART bridges.
• ESP32-C3 and ESP32-H2 have a USB Serial/JTAG controller primarily for console and debugging, not for general-purpose TinyUSB device classes via that port.
• ESP-IDF uses the TinyUSB stack for implementing USB device functionalities.
• USB Descriptors (Device, Configuration, Interface, Endpoint, String) are crucial for device enumeration and telling the host about the device’s capabilities.
• USB Device Classes (like CDC, HID, MSC) standardize device interactions. CDC-ACM allows the ESP32 to appear as a virtual COM port.
• Proper configuration in menuconfig is essential for enabling TinyUSB and specific USB classes.
• Careful attention to board connections (native USB vs. UART bridge) and variant capabilities is necessary for successful USB development.

Further Reading

• ESP-IDF Programming Guide – USB Device (TinyUSB):
  • https://docs.espressif.com/projects/esp-idf/en/v5.4/esp32s2/api-reference/peripherals/usb_device.html (Navigate to S3 or C6 sections for their specific details if needed, the TinyUSB concepts are similar).
• TinyUSB Stack Documentation:
  • https://docs.tinyusb.org/
• ESP-IDF TinyUSB Examples on GitHub:
  • https://github.com/espressif/esp-idf/tree/v5.4/examples/peripherals/usb/device (Contains examples for CDC, HID, MSC, etc.)
• USB Implementers Forum (USB-IF) Specifications:
  • https://www.usb.org/documents (For deep dives into USB standards).
• “USB Complete: The Developer’s Guide” by Jan Axelson: A comprehensive book on USB technology (though not specific to ESP32, it covers fundamentals well).