Note

This component is currently in beta. Its API, behavior, and compatibility may change at any time and without notice; backward compatibility is not guaranteed. Use caution when integrating into production systems.

Overview

The esp_hal_usb component provides a Hardware Abstraction Layer for USB controllers and PHYs across all ESP-IDF supported targets. USB (Universal Serial Bus) enables communication between the ESP device and USB hosts or devices, supporting various USB speeds and transfer types for data exchange.

Architecture

The USB HAL is structured in two main sub-layers:

HAL Layer (Upper): Defines the operational steps and data structures required to control USB peripherals (e.g., initialization, endpoint configuration, transfer management, PHY control).
Low-Level Layer (Bottom): Serves as a translation layer between the HAL and the register files defined in the soc component, handling target-specific register configurations.

Supported USB Controllers and PHYs

This HAL supports various USB controller and PHY types depending on the ESP chip:

USB-DWC (DesignWare USB Controller): The main USB OTG controller supporting USB Host and Device modes
USB Serial JTAG: A special USB peripheral that combines USB CDC-ACM functionality with JTAG debugging capabilities
USB WRAP: A wrapper/peripheral controller that provides additional USB functionality and GPIO matrix integration
USB PHY Types:
- FSLS (Full Speed/Low Speed) Internal PHY: Built-in PHY supporting USB Full Speed and Low Speed operation
- FSLS External PHY: Support for external FSLS PHY via GPIO matrix
- UTMI PHY: UTMI+ compliant PHY interface for High Speed USB support

Features

USB controller initialization and configuration
Endpoint management (IN/OUT endpoints)
Transfer type support (Control, Bulk, Interrupt, Isochronous)
USB speed detection and configuration (High Speed, Full Speed, Low Speed)
FIFO configuration and management
PHY initialization and control (FSLS and UTMI)
GPIO matrix signal routing for USB PHY interfaces
OTG (On-The-Go) signal handling
Interrupt management and event handling
Multi-controller support (on chips with multiple USB controllers)

Usage

The HAL functions primarily serve ESP-IDF USB drivers, primarily the USB Host stack.

Dependencies

soc: Provides chip-specific register definitions
hal: Core hardware abstraction utilities and macros