USB 主机 CDC

iot_usbh_cdc 组件实现了一个 USB 主机 CDC 驱动的简化版本，用户可以通过简单的配置来使用 USB CDC 设备。该组件支持热插拔，并且可以选择性地启用内部环形缓冲区以简化数据收发。

使用指南

使用 usbh_cdc_driver_install 配置, 用户可以配置好 USB CDC 驱动程序，并通过设置 skip_init_usb_host_driver 配置项，在组件内部初始化好 USB HOST Driver 协议栈。当其他 USB 驱动程序也需要使用 USB Host Driver 协议栈时，可以将该配置项设置为 true，以避免重复初始化。

/* 安装 USB CDC 驱动，并由驱动内部初始化好 USB Host 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);

使用 usbh_cdc_register_dev_event_cb 注册一个 CDC 设备事件，并配置好设备匹配列表 dev_match_id_list，当有新的 USB 设备连接时，驱动程序将根据该列表来匹配设备。如果有任何一项匹配成功，驱动程序将调用该回调函数。用户可以在这个函数中使用 usbh_cdc_port_open 函数根据应用的需要选择打开设备的一个或者多个端口用于通信。

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);

参数 dev_match_id_list 指针需要传入一个不在栈上的数组，并且必须以空项结尾。数组中的一项可以是用于匹配一个或多个设备的条件，例如上面的例子中，使用 USB_DEVICE_VENDOR_ANY 和 USB_DEVICE_PRODUCT_ANY 来匹配所有的 USB 设备。用户也可以指定特定的 idVendor 和 idProduct 来匹配特定的设备。还可以通过 match_flags 来指定更多的匹配条件，例如 USB_DEVICE_ID_MATCH_DEV_CLASS， USB_DEVICE_ID_MATCH_DEV_SUBCLASS， USB_DEVICE_ID_MATCH_DEV_PROTOCOL 等等。更多的匹配条件可以参考 usb_dev_match_flags_t。

在 device_event_cb 回调函数中不允许调用 usbh_cdc_write_bytes 等对设备进行通信的函数，因为此回调函数的上下文是在 USB 任务中，调用这些函数会导致死锁。建议在 device_event_cb 回调中创建一个新的任务或者发送一个事件到应用任务中，在新的任务或者应用任务中进行设备通信。

端口打开之后，主机将自动从 CDC 设备接收 USB 数据到 USB 缓冲区，用户可以轮询 usbh_cdc_get_rx_buffer_size 以读取缓冲数据大小，或者注册接收回调以在数据准备就绪时得到通知。然后 usbh_cdc_read_bytes 可以用于读取缓冲数据。当 in_ringbuf_size 大于 0 时，驱动程序将启用内部 ringbuffer 来缓存接收到的数据。
usbh_cdc_write_bytes 可以用于向 USB 设备发送数据。当 out_ringbuf_size 大于 0 时，数据会首先被写入内部传输 ringbuffer，而不是直接写入到 USB 缓冲区。
usbh_cdc_port_close 可以关闭 USB CDC 端口，释放掉其资源。
usbh_cdc_driver_uninstall 可以完全卸载 USB 驱动程序以释放所有资源，当仍有设备连接时，无法直接卸载驱动程序。

备注

由于 USB 设备的热插拔是异步的，因此 USB 设备可能会在运行时的任何时候被拔出。用户需要确保在调用 usbh_cdc_write_bytes 或 usbh_cdc_read_bytes 等函数时，设备仍然连接且端口已打开，否则这些函数将返回错误。

支持的 CDC 设备描述符

驱动支持如下的标准 CDC 设备描述符：

        ------------------- 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)

还支持部分厂商自定义的 CDC 设备描述符，例如：

        ---------------- 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)

备注

在使用 USB HUB 连接多个设备时，如果出现主机的 channel 已经不够使用的情况，可以尝试通过 usbh_cdc_port_config_t 中的 flags 打开 USBH_CDC_FLAGS_DISABLE_NOTIFICATION 标志位，强制禁用中断端点减少一个 channel 的使用，如果设备本身就没有中断端点则无效。

示例代码

usb/host/usb_cdc_basic

API 参考

Header File

components/usb/iot_usbh_cdc/include/iot_usbh_cdc.h

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:

Verifies input arguments and state.
Optionally initializes the USB host driver.
Allocates memory for the USB CDC object.
Creates necessary synchronization primitives (event group, mutex).
Creates the driver task.
Registers the USB host client with the provided configuration.
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.

备注

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

参数

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

返回

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.

返回

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.

参数

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

返回

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.

参数

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

返回

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.

参数

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

返回

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.

参数

cdc_port_handle – [in] The CDC port handle to close

返回

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.

参数

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

返回

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.

参数

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

返回

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.

备注

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.

参数

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

返回

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.

参数

cdc_port_handle – [in] The CDC port handle

返回

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.

参数

cdc_port_handle – [in] The CDC port handle

返回

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.

参数

cdc_port_handle – [in] The CDC port handle
size – [out] Pointer to store the size of the receive buffer

返回

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.

参数

cdc_port_handle – [in] The CDC port handle

返回

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.

参数

cdc_port_handle – [in] The CDC port handle
dev_handle – [out] Pointer to store the device handle

返回

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.

参数

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

返回

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

components/usb/iot_usbh_cdc/include/usbh_helper.h

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.

参数

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

返回

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.

参数

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

返回

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.

参数

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

返回

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.

参数

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

返回

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.

参数

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

返回

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

提供有关此文档的反馈