USB 主机 CDC

iot_usbh_cdc 组件实现了一个 USB 主机 CDC 驱动的简化版本。该 API 的设计类似于 ESP-IDF UART 驱动程序，可在一些应用中替代 UART，快速实现从 UART 到 USB 的迁移。

使用指南

使用 usbh_cdc_driver_install 配置，用户可以简单配置 bulk 端点地址和内部 ringbuffer 的大小，除此之外，用户还可以配置热插拔相关的回调函数 conn_callback disconn_callback：

/* 安装 USB 主机 CDC 驱动程序，配置 bulk 端点地址和内部 ringbuffer 的大小 */
static usbh_cdc_config_t config = {
    /* use default endpoint descriptor with user address */
    .bulk_in_ep_addr = EXAMPLE_BULK_IN_EP_ADDR,
    .bulk_out_ep_addr = EXAMPLE_BULK_OUT_EP_ADDR,
    .rx_buffer_size = IN_RINGBUF_SIZE,
    .tx_buffer_size = OUT_RINGBUF_SIZE,
    .conn_callback = usb_connect_callback,
    .disconn_callback = usb_disconnect_callback,
};
/* 如果用户想要使用多个接口，可以像这样配置 */
#if (EXAMPLE_BULK_ITF_NUM > 1)
config.itf_num = 2;
config.bulk_in_ep_addrs[1] = EXAMPLE_BULK_IN1_EP_ADDR;
config.bulk_out_ep_addrs[1] = EXAMPLE_BULK_OUT1_EP_ADDR;
config.rx_buffer_sizes[1] = IN_RINGBUF_SIZE;
config.tx_buffer_sizes[1] = OUT_RINGBUF_SIZE;
#endif

/* 安装 USB 主机 CDC 驱动程序 */
usbh_cdc_driver_install(&config);

/* 等待 USB 设备连接 */
usbh_cdc_wait_connect(portMAX_DELAY);

驱动程序初始化后，内部状态机将自动处理 USB 的热插拔。
usbh_cdc_wait_connect 可以用于阻塞任务，直到 USB CDC 设备连接或超时。
成功连接后，主机将自动从 CDC 设备接收 USB 数据到内部 ringbuffer，用户可以轮询 usbh_cdc_get_buffered_data_len 以读取缓冲数据大小，或者注册接收回调以在数据准备就绪时得到通知。然后 usbh_cdc_read_bytes 可以用于读取缓冲数据。
usbh_cdc_write_bytes 可以用于向 USB 设备发送数据。数据首先被写入内部传输 ringbuffer，然后在 USB 总线空闲时发送出去。
usbh_cdc_driver_delete 可以完全卸载 USB 驱动程序以释放所有资源。
如果配置多个 CDC 接口，每个接口都包含一个 IN 和 OUT 端点。用户可以使用 usbh_cdc_itf_read_bytes 和 usbh_cdc_itf_write_bytes 与指定的接口通信。

示例代码

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_config_t *config)

Install USB CDC driver.

参数: config – USB Host CDC configs
返回: ESP_ERR_INVALID_STATE driver has been installed ESP_ERR_INVALID_ARG args not supported ESP_FAIL driver install failed ESP_OK driver install succeed

esp_err_t usbh_cdc_driver_delete(void)

Uninstall USB driver.

返回: ESP_ERR_INVALID_STATE driver not installed ESP_OK start succeed

esp_err_t usbh_cdc_wait_connect(TickType_t ticks_to_wait)

Waiting until CDC device connected.

参数: ticks_to_wait – timeout value, count in RTOS ticks
返回: ESP_ERR_INVALID_STATE driver not installed ESP_ERR_TIMEOUT wait timeout ESP_OK device connect succeed

int usbh_cdc_write_bytes(const uint8_t *buf, size_t length)

Send data to interface 0 of connected USB device from a given buffer and length, this function will return after copying all the data to tx ringbuffer.

参数

buf – data buffer address
length – data length to send

返回

int The number of bytes pushed to the tx buffer

int usbh_cdc_itf_write_bytes(uint8_t itf, const uint8_t *buf, size_t length)

Send data to specified interface of connected USB device from a given buffer and length, this function will return after copying all the data to tx buffer.

参数

itf – the interface index
buf – data buffer address
length – data length to send

返回

int The number of bytes pushed to the tx buffer

esp_err_t usbh_cdc_get_buffered_data_len(size_t *size)

Get USB interface 0 rx buffered data length.

参数: size – data length buffered
返回: ESP_ERR_INVALID_STATE cdc not configured, or not running ESP_ERR_INVALID_ARG args not supported ESP_OK start succeed

esp_err_t usbh_cdc_itf_get_buffered_data_len(uint8_t itf, size_t *size)

Get USB specified interface rx buffered data length.

参数

itf – the interface index
size – data length buffered

返回

ESP_ERR_INVALID_STATE cdc not configured, or not running ESP_ERR_INVALID_ARG args not supported ESP_OK start succeed

int usbh_cdc_read_bytes(uint8_t *buf, size_t length, TickType_t ticks_to_wait)

Read data bytes from interface 0 rx buffer.

参数

buf – data buffer address
length – data buffer size
ticks_to_wait – timeout value, count in RTOS ticks

返回

int the number of bytes actually read from rx buffer

int usbh_cdc_itf_read_bytes(uint8_t itf, uint8_t *buf, size_t length, TickType_t ticks_to_wait)

Read data bytes from specified interface rx buffer.

参数

itf – the interface index
buf – data buffer address
length – data buffer size
ticks_to_wait – timeout value, count in RTOS ticks

返回

int the number of bytes actually read from rx buffer

int usbh_cdc_get_itf_state(uint8_t itf)

Get the connect state of given interface.

参数: itf – the interface index
返回: ** int true is ready, false is not ready

esp_err_t usbh_cdc_flush_rx_buffer(uint8_t itf)

Flush rx buffer, discard all the data in the ring-buffer.

参数: itf – the interface index
返回: ** esp_err_t ESP_ERR_INVALID_STATE cdc not configured, or not running ESP_ERR_INVALID_ARG args not supported ESP_OK start succeed

esp_err_t usbh_cdc_flush_tx_buffer(uint8_t itf)

Flush tx buffer, discard all the data in the ring-buffer.

参数: itf – the interface index
返回: ** esp_err_t ESP_ERR_INVALID_STATE cdc not configured, or not running ESP_ERR_INVALID_ARG args not supported ESP_OK start succeed

Structures

struct usbh_cdc_config

USB host CDC configuration type itf_num is the total enabled interface numbers, can not exceed CDC_INTERFACE_NUM_MAX, itf_num = 0 is same as itf_num = 1 for back compatibility, if itf_num > 1, user should config params with s ending like bulk_in_ep_addrs to config each interface, callbacks should not in block state.

Public Members

int itf_num: interface numbers enabled

uint8_t bulk_in_ep_addr: USB CDC bulk in endpoint address, will be overwritten if bulk_in_ep is specified

uint8_t bulk_in_ep_addrs[CDC_INTERFACE_NUM_MAX]: USB CDC bulk in endpoints addresses, saved as an array, will be overwritten if bulk_in_ep is specified

uint8_t bulk_out_ep_addr: USB CDC bulk out endpoint address, will be overwritten if bulk_out_ep is specified

uint8_t bulk_out_ep_addrs[CDC_INTERFACE_NUM_MAX]: USB CDC bulk out endpoint addresses, saved as an array, will be overwritten if bulk_out_ep is specified

int rx_buffer_size: USB receive/in ringbuffer size

int rx_buffer_sizes[CDC_INTERFACE_NUM_MAX]: USB receive/in ringbuffer size of each interface

int tx_buffer_size: USB transmit/out ringbuffer size

int tx_buffer_sizes[CDC_INTERFACE_NUM_MAX]: USB transmit/out ringbuffer size of each interface

usb_ep_desc_t *bulk_in_ep: USB CDC bulk in endpoint descriptor, set NULL if using default param

usb_ep_desc_t *bulk_in_eps[CDC_INTERFACE_NUM_MAX]: USB CDC bulk in endpoint descriptors of each interface, set NULL if using default param

usb_ep_desc_t *bulk_out_ep: USB CDC bulk out endpoint descriptor, set NULL if using default param

usb_ep_desc_t *bulk_out_eps[CDC_INTERFACE_NUM_MAX]: USB CDC bulk out endpoint descriptors of each interface, set NULL if using default param

usbh_cdc_cb_t conn_callback: USB connect callback, set NULL if not use

usbh_cdc_cb_t disconn_callback: USB disconnect callback, set NULL if not use

usbh_cdc_cb_t rx_callback: packet receive callback, set NULL if not use

usbh_cdc_cb_t rx_callbacks[CDC_INTERFACE_NUM_MAX]: packet receive callbacks of each interface, set NULL if not use

void *conn_callback_arg: USB connect callback arg, set NULL if not use

void *disconn_callback_arg: USB disconnect callback arg, set NULL if not use

void *rx_callback_arg: packet receive callback arg, set NULL if not use

void *rx_callback_args[CDC_INTERFACE_NUM_MAX]: packet receive callback arg of each interface, set NULL if not use

Macros

CDC_INTERFACE_NUM_MAX

Type Definitions

typedef void (*usbh_cdc_cb_t)(void *arg): USB receive callback type.

typedef struct usbh_cdc_config usbh_cdc_config_t: USB host CDC configuration type itf_num is the total enabled interface numbers, can not exceed CDC_INTERFACE_NUM_MAX, itf_num = 0 is same as itf_num = 1 for back compatibility, if itf_num > 1, user should config params with s ending like bulk_in_ep_addrs to config each interface, callbacks should not in block state.

提供有关此文档的反馈