USB Host CDC

[中文]

The iot_usbh_cdc component implements a simple version of the USB host CDC driver. The API is designed similar like ESP-IDF UART driver, which can be used to replace the original UART driver to realize the update from UART to USB.

User Guide

Using usbh_cdc_driver_install to configure, user can simply configure the bulk endpoint address and the size of the internal ringbuffer, user can also configure the hot plug related callback function conn_callback disconn_callback.

/* install usbh cdc driver with bulk endpoint configs and size of internal 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 user want to use multiple interfaces, can configure like this */
#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

/* install USB host CDC driver */
usbh_cdc_driver_install(&config);

/* Waiting for USB device connected */
usbh_cdc_wait_connect(portMAX_DELAY);

After the driver initialization, the internal state machine will automatically handle the hot plug of the USB.
usbh_cdc_wait_connect can be used to block task until USB CDC Device is connected or timeout.
After successfully connected, the host will automatically receive USB data from CDC device to the internal ringbuffer, user can poll usbh_cdc_get_buffered_data_len to read buffered data size or register a receive callback to get notified when data is ready. Then usbh_cdc_read_bytes can be used to read buffered data out.
usbh_cdc_write_bytes can be used to send data to USB Device. The data is first written to the internal transmit ringbuffer，then will be sent out during USB bus free.
usbh_cdc_driver_delete can uninstall the USB driver completely to release all resources.
If config multiple CDC interfaces, each interface contains an IN and OUT endpoint. Users can communicate with the specified interfaces using usbh_cdc_itf_read_bytes and usbh_cdc_itf_write_bytes.

Examples

usb/host/usb_cdc_basic

API Reference

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.

Parameters: config – USB Host CDC configs
Returns: 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.

Returns: 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.

Parameters: ticks_to_wait – timeout value, count in RTOS ticks
Returns: 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.

Parameters

buf – data buffer address
length – data length to send

Returns

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.

Parameters

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

Returns

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.

Parameters: size – data length buffered
Returns: 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.

Parameters

itf – the interface index
size – data length buffered

Returns

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.

Parameters

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

Returns

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.

Parameters

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

Returns

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.

Parameters: itf – the interface index
Returns: ** 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.

Parameters: itf – the interface index
Returns: ** 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.

Parameters: itf – the interface index
Returns: ** 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.

Provide feedback about this document