USB Host CDC

[中文]

The iot_usbh_cdc component implements a simplified USB host CDC driver. With simple configuration, users can use USB CDC devices. The component supports hot‑plug and optionally enables an internal ring buffer to simplify data sending and receiving.

Usage Guide

  1. Use usbh_cdc_driver_install to configure the USB CDC driver. By setting the skip_init_usb_host_driver option, the component can initialize the USB Host Driver stack internally. When other USB drivers also need to use the USB Host Driver stack, set this option to true to avoid repeated initialization.

/* Install the USB CDC driver and initialize the USB Host Driver stack inside the driver */
usbh_cdc_driver_config_t config = {
    .task_stack_size = 1024 * 4,
    .task_priority = 5,
    .task_coreid = 0,
    .skip_init_usb_host_driver = false,
};
usbh_cdc_driver_install(&config);

  1. Use usbh_cdc_register_dev_event_cb to register a CDC device event, and configure the device match list dev_match_id_list. When a new USB device is connected, the driver will match it against this list. If any item matches, the driver will invoke the event callback. In this callback, the user can call usbh_cdc_port_open to open one or more ports of the device for communication as needed by the application.

static void device_event_cb(usbh_cdc_device_event_t event, usbh_cdc_device_event_data_t *event_data, void *user_ctx)
{
    switch (event) {
    case CDC_HOST_DEVICE_EVENT_CONNECTED: {
        ESP_LOGI(TAG, "Device connected: dev_addr=%d, matched_intf_num=%d",
                event_data->new_dev.dev_addr, event_data->new_dev.matched_intf_num);

        usbh_cdc_port_handle_t cdc_port = NULL;
        usbh_cdc_port_config_t cdc_port_config = {
            .dev_addr = event_data->new_dev.dev_addr,
            .itf_num = 0,
            .in_transfer_buffer_size = 512,
            .out_transfer_buffer_size = 512,
            .cbs = {
                .notif_cb = NULL,
                .recv_data = NULL,
                .closed = NULL,
                .user_data = NULL,
            },
        };
        usbh_cdc_port_open(&cdc_port_config, &cdc_port);
        } break;

    case CDC_HOST_DEVICE_EVENT_DISCONNECTED:
        ESP_LOGI(TAG, "Device disconnected: dev_addr=%d, dev_hdl=%p",
                event_data->dev_gone.dev_addr, event_data->dev_gone.dev_hdl);
        break;

    default:
        break;
    }
}

const static usb_device_match_id_t match_id_list[] = {
    {
        .match_flags = USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT,
        .idVendor = USB_DEVICE_VENDOR_ANY,
        .idProduct = USB_DEVICE_PRODUCT_ANY,
    },
    { 0 }
};
usbh_cdc_register_dev_event_cb(match_id_list, device_event_cb, NULL);

The parameter dev_match_id_list pointer requires an array that is not on the stack and must be null-terminated. An array entry can specify conditions to match one or more devices. For example, the above example uses USB_DEVICE_VENDOR_ANY and USB_DEVICE_PRODUCT_ANY to match all USB devices. Users can also specify specific idVendor and idProduct to match specific devices. You can further specify conditions using match_flags, such as USB_DEVICE_ID_MATCH_DEV_CLASS, USB_DEVICE_ID_MATCH_DEV_SUBCLASS, USB_DEVICE_ID_MATCH_DEV_PROTOCOL, etc. For more matching conditions, see usb_dev_match_flags_t.

Do not call communication functions such as usbh_cdc_write_bytes in the device_event_cb callback, because this callback runs in the USB task context and calling these functions can cause a deadlock. It is recommended to create a new task in the device_event_cb callback or send an event to the application task, and perform device communication in the new task or the application task.

  1. After a port is opened, the host will automatically receive USB data from the CDC device into the USB buffer. The user can poll usbh_cdc_get_rx_buffer_size to read the buffered data length, or register a receive callback to be notified when data is ready. Then usbh_cdc_read_bytes can be used to read the buffered data. When in_ringbuf_size is greater than 0, the driver enables an internal ring buffer to cache received data.

  2. usbh_cdc_write_bytes can be used to send data to the USB device. When out_ringbuf_size is greater than 0, data is first written to the internal transmission ringbuffer instead of directly to the USB buffer.

  3. usbh_cdc_port_close can delete the USB CDC device and release its resources.

  4. usbh_cdc_driver_uninstall can fully uninstall the USB driver to release all resources; if a device is still connected, the driver cannot be uninstalled directly.

Note

Since USB device hot‑plug is asynchronous, a USB device may be unplugged at any time during runtime. Users must ensure that when calling functions such as usbh_cdc_write_bytes or usbh_cdc_read_bytes, the device is still connected and the port is open; otherwise these functions will return an error.

Supported CDC Device Descriptors

The driver supports the following standard CDC device descriptors:

        ------------------- IAD Descriptor --------------------
bLength                  : 0x08 (8 bytes)
bDescriptorType          : 0x0B (Interface Association Descriptor)
bFirstInterface          : 0x00 (Interface 0)
bInterfaceCount          : 0x02 (2 Interfaces)
bFunctionClass           : 0x02 (Communications and CDC Control)
bFunctionSubClass        : 0x06
bFunctionProtocol        : 0x00
iFunction                : 0x07 (String Descriptor 7)
Language 0x0409         : ""

        ---------------- Interface Descriptor -----------------
bLength                  : 0x09 (9 bytes)
bDescriptorType          : 0x04 (Interface Descriptor)
bInterfaceNumber         : 0x00 (Interface 0)
bAlternateSetting        : 0x00
bNumEndpoints            : 0x01 (1 Endpoint)
bInterfaceClass          : 0x02 (Communications and CDC Control)
bInterfaceSubClass       : 0x06 (Ethernet Networking Control Model)
bInterfaceProtocol       : 0x00 (No class specific protocol required)
iInterface               : 0x07 (String Descriptor 7)
Language 0x0409         : ""

        ----------------- Endpoint Descriptor -----------------
bLength                  : 0x07 (7 bytes)
bDescriptorType          : 0x05 (Endpoint Descriptor)
bEndpointAddress         : 0x87 (Direction=IN EndpointID=7)
bmAttributes             : 0x03 (TransferType=Interrupt)
wMaxPacketSize           : 0x0020
Bits 15..13             : 0x00 (reserved, must be zero)
Bits 12..11             : 0x00 (0 additional transactions per microframe -> allows 1..1024 bytes per packet)
Bits 10..0              : 0x20 (32 bytes per packet)
bInterval                : 0x09 (256 microframes -> 32 ms)

        ---------------- Interface Descriptor -----------------
bLength                  : 0x09 (9 bytes)
bDescriptorType          : 0x04 (Interface Descriptor)
bInterfaceNumber         : 0x01 (Interface 1)
bAlternateSetting        : 0x00
bNumEndpoints            : 0x00 (Default Control Pipe only)
bInterfaceClass          : 0x0A (CDC-Data)
bInterfaceSubClass       : 0x00
bInterfaceProtocol       : 0x00
iInterface               : 0x00 (No String Descriptor)

        ---------------- Interface Descriptor -----------------
bLength                  : 0x09 (9 bytes)
bDescriptorType          : 0x04 (Interface Descriptor)
bInterfaceNumber         : 0x01 (Interface 1)
bAlternateSetting        : 0x01
bNumEndpoints            : 0x02 (2 Endpoints)
bInterfaceClass          : 0x0A (CDC-Data)
bInterfaceSubClass       : 0x00
bInterfaceProtocol       : 0x00
iInterface               : 0x00 (No String Descriptor)

        ----------------- Endpoint Descriptor -----------------
bLength                  : 0x07 (7 bytes)
bDescriptorType          : 0x05 (Endpoint Descriptor)
bEndpointAddress         : 0x0C (Direction=OUT EndpointID=12)
bmAttributes             : 0x02 (TransferType=Bulk)
wMaxPacketSize           : 0x0200 (max 512 bytes)
bInterval                : 0x00 (never NAKs)

        ----------------- Endpoint Descriptor -----------------
bLength                  : 0x07 (7 bytes)
bDescriptorType          : 0x05 (Endpoint Descriptor)
bEndpointAddress         : 0x83 (Direction=IN EndpointID=3)
bmAttributes             : 0x02 (TransferType=Bulk)
wMaxPacketSize           : 0x0200 (max 512 bytes)
bInterval                : 0x00 (never NAKs)

The driver also supports some vendor-specific CDC device descriptors, for example:

        ---------------- Interface Descriptor -----------------
bLength                  : 0x09 (9 bytes)
bDescriptorType          : 0x04 (Interface Descriptor)
bInterfaceNumber         : 0x03 (Interface 3)
bAlternateSetting        : 0x00
bNumEndpoints            : 0x03 (3 Endpoints)
bInterfaceClass          : 0xFF (Vendor Specific)
bInterfaceSubClass       : 0x00
bInterfaceProtocol       : 0x00
iInterface               : 0x09 (String Descriptor 9)
Language 0x0409         : "Mobile AT Interface"

        ----------------- Endpoint Descriptor -----------------
bLength                  : 0x07 (7 bytes)
bDescriptorType          : 0x05 (Endpoint Descriptor)
bEndpointAddress         : 0x85 (Direction=IN EndpointID=5)
bmAttributes             : 0x03 (TransferType=Interrupt)
wMaxPacketSize           : 0x0010
Bits 15..13             : 0x00 (reserved, must be zero)
Bits 12..11             : 0x00 (0 additional transactions per microframe -> allows 1..1024 bytes per packet)
Bits 10..0              : 0x10 (16 bytes per packet)
bInterval                : 0x09 (256 microframes -> 32 ms)

        ----------------- Endpoint Descriptor -----------------
bLength                  : 0x07 (7 bytes)
bDescriptorType          : 0x05 (Endpoint Descriptor)
bEndpointAddress         : 0x82 (Direction=IN EndpointID=2)
bmAttributes             : 0x02 (TransferType=Bulk)
wMaxPacketSize           : 0x0200 (max 512 bytes)
bInterval                : 0x00 (never NAKs)

        ----------------- Endpoint Descriptor -----------------
bLength                  : 0x07 (7 bytes)
bDescriptorType          : 0x05 (Endpoint Descriptor)
bEndpointAddress         : 0x0B (Direction=OUT EndpointID=11)
bmAttributes             : 0x02 (TransferType=Bulk)
wMaxPacketSize           : 0x0200 (max 512 bytes)
bInterval                : 0x00 (never NAKs)

Note

When connecting multiple devices using a USB HUB, if the HOST’s channels are insufficient, you can try enabling the USBH_CDC_FLAGS_DISABLE_NOTIFICATION flag in usbh_cdc_port_config_t to forcibly disable interrupt endpoint and reduce the use of one channel. This will not work if the device itself does not have interrupt endpoint.

Example Code

usb/host/usb_cdc_basic

API Reference

Header File

Functions

esp_err_t usbh_cdc_driver_install(const usbh_cdc_driver_config_t *config)

Install the USB CDC driver.

This function installs and initializes the USB CDC driver. It sets up internal data structures, creates necessary tasks, and registers the USB host client. If the USB host driver is not already initialized, it will create and initialize it.

The function performs the following steps:

  1. Verifies input arguments and state.

  2. Optionally initializes the USB host driver.

  3. Allocates memory for the USB CDC object.

  4. Creates necessary synchronization primitives (event group, mutex).

  5. Creates the driver task.

  6. Registers the USB host client with the provided configuration.

  7. Initializes the CDC driver structure and resumes the driver task.

In case of an error, the function will clean up any resources that were allocated before the failure occurred.

Note

If the skip_init_usb_host_driver flag in the config is set to true, the function will skip the USB host driver initialization.

Parameters

config – [in] Pointer to a configuration structure (usbh_cdc_driver_config_t)

Returns

  • ESP_OK: Driver installed successfully

  • ESP_ERR_INVALID_ARG: Null configuration parameter or invalid arguments

  • ESP_ERR_INVALID_STATE: USB CDC driver already installed

  • ESP_ERR_NO_MEM: Memory allocation failed

  • ESP_FAIL: Failed to create necessary tasks or USB host installation failed

esp_err_t usbh_cdc_driver_uninstall(void)

Uninstall the USB CDC driver.

This function uninstalls the USB CDC driver, releasing any allocated resources and stopping all driver-related tasks. It ensures that all CDC devices are closed before proceeding with the uninstallation.

Returns

  • ESP_OK: Driver uninstalled successfully

  • ESP_ERR_INVALID_STATE: Driver is not installed or devices are still active

  • ESP_ERR_NOT_FINISHED: Timeout occurred while waiting for the CDC task to finish

esp_err_t usbh_cdc_register_dev_event_cb(const usb_device_match_id_t *dev_match_id_list, usbh_cdc_device_event_callback_t event_cb, void *user_data)

Register an additional callback function for new device detection.

This function registers a callback that will be invoked when a new USB CDC device is connected. The callback will be automatically unregistered when usbh_cdc_driver_uninstall() is called.

Parameters

  • dev_match_id_list – [in] List of device match IDs to filter devices that the callback will be called for The list should be terminated with a NULL entry.

  • event_cb – [in] Callback function to be called when a new device is connected

  • user_data – [in] User data pointer that will be passed to the callback function

Returns

  • ESP_OK: Callback registered successfully

  • ESP_ERR_INVALID_ARG: Invalid CDC handle or callback function

  • ESP_ERR_NO_MEM: Failed to allocate memory for callback registration

esp_err_t usbh_cdc_unregister_dev_event_cb(usbh_cdc_device_event_callback_t event_cb)

Unregister the new device callback which same as the one registered by usbh_cdc_register_dev_event_cb.

Parameters

event_cb – [in] The new device callback function to unregister

Returns

  • ESP_OK: Callback unregistered successfully

  • ESP_ERR_INVALID_ARG: Invalid callback function

esp_err_t usbh_cdc_port_open(const usbh_cdc_port_config_t *port_config, usbh_cdc_port_handle_t *cdc_port_out)

Open a USB CDC port on a USB CDC device.

  • This function opens a USB CDC port on the specified USB CDC device, allowing communication through the port.

Parameters

  • port_config – [in] Pointer to a usb_cdc_port_config_t structure

  • cdc_port_out – [out] Pointer to a variable that will hold the opened CDC port handle upon successful opening

Returns

  • ESP_OK: Port opened successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments (NULL handle or port_config)

  • ESP_ERR_INVALID_STATE: Device is not connected

esp_err_t usbh_cdc_port_close(usbh_cdc_port_handle_t cdc_port_handle)

Close a USB CDC port.

Parameters

cdc_port_handle – [in] The CDC port handle to close

Returns

  • ESP_OK: Port closed successfully

  • ESP_ERR_INVALID_ARG: Invalid CDC port handle provided

  • ESP_ERR_INVALID_STATE: USB CDC driver is not installed or port is not open

esp_err_t usbh_cdc_send_custom_request(usbh_cdc_port_handle_t cdc_port_handle, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint16_t wLength, uint8_t *data)

Send a custom control request to the USB CDC port.

This function sends a custom control request to the USB CDC device with the specified parameters. It can be used for both IN and OUT transfers.

Parameters

  • cdc_port_handle – [in] The CDC port handle to send the request to

  • bmRequestType – [in] The request type bitmask

  • bRequest – [in] The request ID

  • wValue – [in] The request value

  • wIndex – [in] The request index

  • wLength – [in] The length of data to transfer

  • data – [inout] Pointer to the data buffer:

    • For OUT transfers: data to be sent to device

    • For IN transfers: buffer to store received data

Returns

  • ESP_OK: Request sent successfully

  • ESP_ERR_INVALID_ARG: Invalid arguments (NULL handle/data buffer)

  • ESP_ERR_INVALID_STATE: Device is not connected

  • ESP_ERR_TIMEOUT: Control transfer timed out

  • ESP_ERR_INVALID_RESPONSE: Control transfer failed

esp_err_t usbh_cdc_write_bytes(usbh_cdc_port_handle_t cdc_port_handle, const uint8_t *buf, size_t length, TickType_t ticks_to_wait)

Write data to the USB CDC port.

With internal ring buffer, this function writes data to the specified USB CDC device by pushing the data into the output ring buffer. If the buffer is full or the device is not connected, the write will fail.

Without internal ring buffer, this function writes data to the specified USB CDC device by sending data directly to the device. Please set the ticks_to_wait for blocking write.

Parameters

  • cdc_port_handle – [in] The CDC port handle

  • buf – [in] Pointer to the data buffer to write

  • length – [in] Pointer to the length of data to write. On success, it remains unchanged, otherwise set to 0.

  • ticks_to_wait – [in] The maximum amount of time to wait for the write operation to complete

Returns

  • ESP_OK: Data written successfully

  • ESP_ERR_INVALID_ARG: Invalid argument (NULL handle, buffer, or length)

  • ESP_ERR_INVALID_STATE: Device is not connected

esp_err_t usbh_cdc_read_bytes(usbh_cdc_port_handle_t cdc_port_handle, uint8_t *buf, size_t *length, TickType_t ticks_to_wait)

Read data from the USB CDC port.

With internal ring buffer, this function reads data from the specified USB CDC device by popping data from the input ring buffer. If no data is available or the device is not connected, the read will fail.

Without internal ring buffer, this function reads data from the specified USB CDC device by receiving data directly from the device. You can call this function in the recv_data callback function. Please set ticks_to_wait to zero for non-blocking read.

Note

If the port is not opened with ring buffer, the length must be equal to the internal transfer buffer size, otherwise the function will return ESP_ERR_INVALID_ARG.

Parameters

  • cdc_port_handle – [in] The CDC port handle

  • buf – [out] Pointer to the buffer where the read data will be stored

  • length – [inout] Pointer to the length of data to read. On success, it is updated with the actual bytes read.

  • ticks_to_wait – [in] The maximum amount of time to wait for the read operation to complete

Returns

  • ESP_OK: Data read successfully

  • ESP_FAIL: Failed to read data

  • ESP_ERR_INVALID_ARG: Invalid argument (NULL handle, buffer, or length)

  • ESP_ERR_INVALID_STATE: Device is not connected

esp_err_t usbh_cdc_flush_rx_buffer(usbh_cdc_port_handle_t cdc_port_handle)

Flush the receive buffer of the USB CDC port.

This function clears the receive buffer, discarding any data currently in the buffer.

Not supported for no internal ring buffer mode.

Parameters

cdc_port_handle – [in] The CDC port handle

Returns

  • ESP_OK: Receive buffer flushed successfully

  • ESP_ERR_INVALID_ARG: Invalid CDC handle provided

  • ESP_ERR_NOT_SUPPORTED: Not supported for no internal ring buffer mode

esp_err_t usbh_cdc_flush_tx_buffer(usbh_cdc_port_handle_t cdc_port_handle)

Flush the transmit buffer of the USB CDC port.

This function clears the transmit buffer, discarding any data currently in the buffer.

Not supported for no internal ring buffer mode.

Parameters

cdc_port_handle – [in] The CDC port handle

Returns

  • ESP_OK: Transmit buffer flushed successfully

  • ESP_ERR_INVALID_ARG: Invalid CDC handle provided

  • ESP_ERR_NOT_SUPPORTED: Not supported for no internal ring buffer mode

esp_err_t usbh_cdc_get_rx_buffer_size(usbh_cdc_port_handle_t cdc_port_handle, size_t *size)

Get the size of the receive buffer of the USB CDC port.

This function retrieves the current size of the receive buffer in bytes.

For no internal ring buffer, you can call this function in the recv_data callback function.

Parameters

  • cdc_port_handle – [in] The CDC port handle

  • size – [out] Pointer to store the size of the receive buffer

Returns

  • ESP_OK: Size retrieved successfully

  • ESP_ERR_INVALID_ARG: Invalid CDC handle provided

esp_err_t usbh_cdc_desc_print(usbh_cdc_port_handle_t cdc_port_handle)

Print the USB CDC device descriptors.

This function retrieves and prints the USB device and configuration descriptors for the specified USB CDC device. It checks that the device is properly connected and open before retrieving and printing the descriptors.

Parameters

cdc_port_handle – [in] The CDC port handle

Returns

  • ESP_OK: Descriptors printed successfully

  • ESP_ERR_INVALID_ARG: Invalid CDC handle provided

  • ESP_ERR_INVALID_STATE: Device is not connected or not yet open

esp_err_t usbh_cdc_get_dev_handle(usbh_cdc_port_handle_t cdc_port_handle, usb_device_handle_t *dev_handle)

Get the device handle of the USB CDC device.

This function retrieves the device handle associated with the specified USB CDC device.

Parameters

  • cdc_port_handle – [in] The CDC port handle

  • dev_handle – [out] Pointer to store the device handle

Returns

  • ESP_OK: Device handle retrieved successfully

  • ESP_ERR_INVALID_ARG: Invalid CDC handle provided

  • ESP_ERR_INVALID_STATE: Device is not connected or not yet open

esp_err_t usbh_cdc_port_get_intf_desc(usbh_cdc_port_handle_t port_handle, const usb_intf_desc_t **notif_intf, const usb_intf_desc_t **data_intf)

Get the parsed information of the USB CDC device.

Parameters

  • port_handle – [in] The CDC port handle

  • notif_intf – [out] Pointer to store the notification interface descriptor

  • data_intf – [out] Pointer to store the data interface descriptor

Returns

  • ESP_OK: Parsed information retrieved successfully

  • ESP_ERR_INVALID_ARG: Invalid CDC handle provided

  • ESP_ERR_INVALID_STATE: Device is not connected or not yet open

Unions

union usbh_cdc_device_event_data_t
#include <iot_usbh_cdc.h>

USB CDC HOST device event data.

Public Members

uint8_t dev_addr

Device address

int matched_intf_num

Number of matched interface, -1 is invalid

const usb_device_desc_t *device_desc

Device descriptor

const usb_config_desc_t *active_config_desc

Active configuration descriptor

struct usbh_cdc_device_event_data_t::[anonymous] new_dev

New device connected event data

usb_device_handle_t dev_hdl

Device handle for the event

struct usbh_cdc_device_event_data_t::[anonymous] dev_gone

Device gone event data

Structures

struct usbh_cdc_driver_config_t

CDC driver configuration.

Public Members

size_t task_stack_size

Stack size of the driver’s task

unsigned task_priority

Priority of the driver’s task

int task_coreid

Core of the driver’s task, Set it to -1 to not specify the core.

bool skip_init_usb_host_driver

Skip initialization of USB host driver

struct usbh_cdc_port_event_callbacks_t

Callback structure for CDC port events.

Public Members

void (*closed)(usbh_cdc_port_handle_t port_handle, void *user_data)

Callback function for when the CDC port is opened, set NULL if not use.

Param port_handle

[in] Handle to the CDC port that was opened

Param user_data

[in] User data pointer that was passed during callback registration

void (*recv_data)(usbh_cdc_port_handle_t port_handle, void *user_data)

Callback function for when data is received on the CDC port, set NULL if not use.

Param port_handle

[in] Handle to the CDC port that received data

Param user_data

[in] User data pointer that was passed during callback registration

void (*notif_cb)(usbh_cdc_port_handle_t port_handle, iot_cdc_notification_t *notif, void *user_data)

Callback function for when a notification is received on the CDC port, set NULL if not use.

Param port_handle

[in] Handle to the CDC port that received a notification

Param notif

[in] Pointer to the notification data structure containing notification details

Param user_data

[in] User data pointer that was passed during callback registration

void *user_data

Pointer to user data that will be passed to the callbacks

struct usbh_cdc_port_config_t

Configuration structure for initializing a USB CDC port.

Public Members

uint8_t dev_addr

Device address of the CDC device

uint8_t itf_num

Interface number for the CDC port

size_t in_ringbuf_size

Size of the receive ringbuffer size, if set to 0, not use ringbuffer

size_t out_ringbuf_size

Size of the transmit ringbuffer size, if set to 0, not use ringbuffer

size_t in_transfer_buffer_size

Size of the IN transfer buffer size

size_t out_transfer_buffer_size

Size of the OUT transfer buffer size

usbh_cdc_port_event_callbacks_t cbs

Event callbacks for the CDC port

usbh_cdc_port_flags_t flags

Flags for the CDC port configuration

Type Definitions

typedef struct usbh_cdc_port_t *usbh_cdc_port_handle_t
typedef void (*usbh_cdc_device_event_callback_t)(usbh_cdc_device_event_t event, usbh_cdc_device_event_data_t *event_data, void *user_ctx)

USB Host CDC device event callback function.

Param event

[in] Event structure

Param event_data

[in] Event data structure

Param user_ctx

[in] User’s argument passed to callback function

Enumerations

enum usbh_cdc_device_event_t

USB CDC HOST Driver event id.

Values:

enumerator CDC_HOST_DEVICE_EVENT_CONNECTED

Device connected event

enumerator CDC_HOST_DEVICE_EVENT_DISCONNECTED

Device disconnected event

enum usbh_cdc_port_flags_t

Flags for CDC port configuration.

These flags can be used to modify the behavior of the CDC port.

Values:

enumerator USBH_CDC_FLAGS_DISABLE_NOTIFICATION

Force disable notification functionality on the CDC port.

Header File

Functions

int usbh_match_device(const usb_device_desc_t *dev_desc, const usb_device_match_id_t *id)

Match a USB device against a set of criteria.

This function checks if the provided USB device descriptor matches the specified criteria in the match ID. It compares vendor ID, product ID, device class, subclass, protocol, and other fields based on the match flags.

Parameters

  • dev_desc – [in] Pointer to the USB device descriptor to match against

  • id – [in] Pointer to the USB device match ID containing the criteria for matching

Returns

  • 1 if the device matches the criteria

  • 0 if it does not match

int usbh_match_interface(const usb_intf_desc_t *intf_desc, const usb_device_match_id_t *id)

Match a USB interface against a set of criteria.

This function checks if the provided USB interface descriptor matches the specified criteria in the match ID. It compares interface class, subclass, protocol, and other fields based on the match flags.

Parameters

  • intf_desc – [in] Pointer to the USB interface descriptor to match against

  • id – [in] Pointer to the USB device match ID containing the criteria for matching

Returns

  • 1 if the interface matches the criteria

  • 0 if it does not match

int usbh_match_device_from_id_list(const usb_device_desc_t *dev_desc, const usb_device_match_id_t *id_list)

Match a USB device against a set of criteria.

This function checks if the provided USB device descriptor and configuration descriptor match the specified criteria in the match ID. It compares vendor ID, product ID, device class, subclass, protocol, details based on the match flags.

Parameters

  • dev_desc – [in] Pointer to the USB device descriptor to match against

  • id_list – [in] Pointer to list of USB device match ID containing the criteria for matching

Returns

  • 1 if both device match the criteria

  • 0 if they do not match

int usbh_match_interface_in_configuration(const usb_config_desc_t *config_desc, const usb_device_match_id_t *id, int *matched_intf_num)

Match a USB interface in a configuration against a set of criteria.

This function checks if any interface in the provided USB configuration descriptor matches the specified criteria in the match ID. It iterates through all interfaces in the configuration and compares their details based on the match flags.

Parameters

  • config_desc – [in] Pointer to the USB configuration descriptor to search for matching interfaces

  • id – [in] Pointer to the USB device match ID containing the criteria for matching

  • matched_intf_num – [out] Pointer to an integer to store the number of matched interfaces, set NULL if not needed

Returns

  • 1 if any interface matches the criteria

  • 0 if no interface matches

int usbh_match_id_from_list(const usb_device_desc_t *dev_desc, const usb_config_desc_t *config_desc, const usb_device_match_id_t *id_list, int *matched_intf_num)

Match a USB device and interface against a set of criteria.

This function checks if the provided USB device descriptor and configuration descriptor match the specified criteria in the match ID. It compares vendor ID, product ID, device class, subclass, protocol, and interface details based on the match flags.

Parameters

  • dev_desc – [in] Pointer to the USB device descriptor to match against

  • config_desc – [in] Pointer to the USB configuration descriptor to match against

  • id_list – [in] Pointer to list of USB device match ID containing the criteria for matching

  • matched_intf_num – [out] Pointer to an integer to store the number of matched interfaces, set NULL if not needed

Returns

  • 1 if both device and interface match the criteria

  • 0 if they do not match

Structures

struct usb_device_match_id_t

Match a USB device against a set of criteria.

Public Members

usb_dev_match_flags_t match_flags

which fields to match against?

uint16_t idVendor

Vendor ID

uint16_t idProduct

Product ID

uint16_t bcdDevice

Device release number in binary-coded decimal (BCD)

uint8_t bDeviceClass

Device class

uint8_t bDeviceSubClass

Device subclass

uint8_t bDeviceProtocol

Device protocol

uint8_t bInterfaceClass

Interface class

uint8_t bInterfaceSubClass

Interface subclass

uint8_t bInterfaceProtocol

Interface protocol

uint8_t bInterfaceNumber

Interface number

Macros

USB_DEVICE_VENDOR_ANY
USB_DEVICE_PRODUCT_ANY
ESP_USB_DEVICE_MATCH_ID_ANY

Enumerations

enum usb_dev_match_flags_t

Match a USB device against a set of fields.

Values:

enumerator USB_DEVICE_ID_MATCH_VENDOR
enumerator USB_DEVICE_ID_MATCH_PRODUCT
enumerator USB_DEVICE_ID_MATCH_DEV_BCD
enumerator USB_DEVICE_ID_MATCH_DEV_CLASS
enumerator USB_DEVICE_ID_MATCH_DEV_SUBCLASS
enumerator USB_DEVICE_ID_MATCH_DEV_PROTOCOL
enumerator USB_DEVICE_ID_MATCH_INT_CLASS
enumerator USB_DEVICE_ID_MATCH_INT_SUBCLASS
enumerator USB_DEVICE_ID_MATCH_INT_PROTOCOL
enumerator USB_DEVICE_ID_MATCH_INT_NUMBER
enumerator USB_DEVICE_ID_MATCH_ALL
enumerator USB_DEVICE_ID_MATCH_DEV

Match device descriptor

enumerator USB_DEVICE_ID_MATCH_INTF

Match interface descriptor

enumerator USB_DEVICE_ID_MATCH_VID_PID

Match vendor and product ID

Provide feedback about this document