USB 主机 CDC
iot_usbh_cdc
组件实现了一个 USB 主机 CDC 驱动的简化版本。该 API 的设计类似于 ESP-IDF UART 驱动程序,可在一些应用中替代 UART,快速实现从 UART 到 USB 的迁移。
使用指南
使用
usbh_cdc_driver_install
配置, 用户可以配置好 USB CDC 驱动程序,并通过设置skip_init_usb_host_driver
配置项,在组件内部初始化好 USB HOST Driver 协议栈。
/* 安装 USB CDC 驱动,并由驱动内部初始化好 USB Host Driver 协议栈 */
usbh_cdc_driver_config_t config = {
.driver_task_stack_size = 1024 * 4,
.driver_task_priority = 5,
.xCoreID = 0,
.skip_init_usb_host_driver = false,
.new_dev_cb = cdc_new_dev_cb,
};
使用
usbh_cdc_create
配置,用户可以简单配置 itf_num 接口号和内部 ringbuffer 的大小,除此之外,用户还可以配置热插拔相关的回调函数connect
disconnect
revc_data
:
/* 安装 USB 主机 CDC 驱动程序,配置 bulk 端点地址和内部 ringbuffer 的大小 */
usbh_cdc_device_config_t dev_config = {
.vid = 0,
.pid = 0,
.itf_num = 1,
/* 如果设置为 0,则使用默认值 */
.rx_buffer_size = 0,
.tx_buffer_size = 0,
.cbs = {
.connect = cdc_connect_cb,
.disconnect = cdc_disconnect_cb,
.user_data = NULL
},
};
usbh_cdc_handle_t handle = NULL;
usbh_cdc_create(&dev_config, &handle);
/* 如果用户想要使用多个接口,可以像这样配置 */
#if (EXAMPLE_BULK_ITF_NUM > 1)
config.itf_num = 3;
usbh_cdc_handle_t handle2 = NULL;
usbh_cdc_create(&dev_config, &handle2);
#endif
驱动程序初始化后,内部状态机将自动处理 USB 的热插拔。
成功连接后,主机将自动从 CDC 设备接收 USB 数据到内部
ringbuffer
,用户可以轮询usbh_cdc_get_rx_buffer_size
以读取缓冲数据大小,或者注册接收回调以在数据准备就绪时得到通知。然后usbh_cdc_read_bytes
可以用于读取缓冲数据。usbh_cdc_write_bytes
可以用于向 USB 设备发送数据。数据首先被写入内部传输ringbuffer
,然后在 USB 总线空闲时发送出去。usbh_cdc_delete
可以删除 USB CDC 设备,释放掉 ringbuffer 以及其他资源。usbh_cdc_driver_uninstall
可以完全卸载 USB 驱动程序以释放所有资源。
示例代码
API 参考
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:
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 – Pointer to a configuration structure (
usbh_cdc_driver_config_t
) that specifies the driver’s settings such as task stack size, priority, core affinity, and new device callback.- 返回
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_create(const usbh_cdc_device_config_t *config, usbh_cdc_handle_t *cdc_handle)
Create a new USB CDC device handle.
This function allocates and initializes a new USB CDC device based on the provided configuration, including setting up the ring buffers for data transmission and reception, and searching for and opening the appropriate USB device.
- 参数
cdc_handle – [out] Pointer to a variable that will hold the created CDC device handle upon successful creation
config – [in] Pointer to a
usbh_cdc_device_config_t
structure containing the configuration for the new device, including vendor ID (VID), product ID (PID), and buffer sizes
- 返回
ESP_OK: CDC device successfully created
ESP_ERR_INVALID_STATE: USB CDC driver is not installed
ESP_ERR_INVALID_ARG: Null
cdc_handle
orconfig
parameterESP_ERR_NO_MEM: Memory allocation failed or ring buffer creation failed
ESP_FAIL: Failed to open the CDC device
-
esp_err_t usbh_cdc_delete(usbh_cdc_handle_t cdc_handle)
Delete a USB CDC device handle.
This function deletes the specified USB CDC device handle, freeing its associated resources, including ring buffers and semaphores.
备注
When deleting the device, please avoid writing or reading data.
- 参数
cdc_handle – [in] The CDC device handle to delete
- 返回
ESP_OK: CDC device deleted successfully
ESP_ERR_INVALID_STATE: USB CDC driver is not installed
ESP_ERR_INVALID_ARG: Invalid CDC handle provided
-
esp_err_t usbh_cdc_write_bytes(usbh_cdc_handle_t cdc_handle, const uint8_t *buf, size_t length, TickType_t ticks_to_wait)
Write data to the USB CDC device.
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.
- 参数
cdc_handle – [in] The CDC device 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_handle_t cdc_handle, const uint8_t *buf, size_t *length, TickType_t ticks_to_wait)
Read data from the USB CDC device.
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.
- 参数
cdc_handle – [in] The CDC device 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_handle_t cdc_handle)
Flush the receive buffer of the USB CDC device.
This function clears the receive buffer, discarding any data currently in the buffer.
- 参数
cdc_handle – [in] The CDC device handle
- 返回
ESP_OK: Receive buffer flushed successfully
ESP_ERR_INVALID_ARG: Invalid CDC handle provided
-
esp_err_t usbh_cdc_flush_tx_buffer(usbh_cdc_handle_t cdc_handle)
Flush the transmit buffer of the USB CDC device.
This function clears the transmit buffer, discarding any data currently in the buffer.
- 参数
cdc_handle – [in] The CDC device handle
- 返回
ESP_OK: Transmit buffer flushed successfully
ESP_ERR_INVALID_ARG: Invalid CDC handle provided
-
esp_err_t usbh_cdc_get_rx_buffer_size(usbh_cdc_handle_t cdc_handle, size_t *size)
Get the size of the receive buffer of the USB CDC device.
This function retrieves the current size of the receive buffer in bytes.
- 参数
cdc_handle – [in] The CDC device 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_get_state(usbh_cdc_handle_t cdc_handle, usbh_cdc_state_t *state)
Get the connect state of given interface.
- 参数
cdc_handle – [in] The CDC device handle
state – [out] Pointer to store the connect state
- 返回
ESP_OK: Size retrieved successfully
ESP_ERR_INVALID_ARG: Invalid CDC handle provided
-
esp_err_t usbh_cdc_desc_print(usbh_cdc_handle_t cdc_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_handle – [in] The CDC device 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
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
-
usbh_cdc_new_dev_cb_t new_dev_cb
Callback function when a new device is connected
-
size_t task_stack_size
-
struct usbh_cdc_event_callbacks_t
Callback structure for CDC device events.
Public Members
-
usbh_cdc_event_cb_t connect
USB connect callback, set NULL if use
-
usbh_cdc_event_cb_t disconnect
USB disconnect callback, set NULL if not use
-
usbh_cdc_event_cb_t revc_data
USB receive data callback, set NULL if not use
-
void *user_data
Pointer to user data that will be passed to the callbacks
-
usbh_cdc_event_cb_t connect
-
struct usbh_cdc_config
Configuration structure for initializing a USB CDC device.
Public Members
-
uint16_t vid
Vendor ID: If set, the
pid
parameter must be configured If not set, it will default to opening the first connected device
-
uint16_t pid
Product ID: If set, the
vid
parameter must be configured If not set, it will default to opening the first connected device
-
int itf_num
interface numbers
-
size_t rx_buffer_size
Size of the receive buffer, default is 1024 bytes if set to 0
-
size_t tx_buffer_size
Size of the transmit buffer, default is 1024 bytes if set to 0
-
usbh_cdc_event_callbacks_t cbs
Event callbacks for the CDC device
-
uint16_t vid
Macros
-
CDC_HOST_ANY_VID
-
CDC_HOST_ANY_PID
Type Definitions
-
typedef struct usbh_cdc_t *usbh_cdc_handle_t
-
typedef void (*usbh_cdc_new_dev_cb_t)(usb_device_handle_t usb_dev)
New USB device callback.
Provides already opened usb_dev, that will be closed after this callback returns. This is useful for peeking device’s descriptors, e.g. peeking VID/PID and loading proper driver.
- Attention
This callback is called from USB Host context, so the CDC device can’t be opened here.
-
typedef void (*usbh_cdc_event_cb_t)(usbh_cdc_handle_t cdc_handle, void *user_data)
Callback structure for CDC device events.
-
typedef struct usbh_cdc_config usbh_cdc_device_config_t
Configuration structure for initializing a USB CDC device.