From 81448dcae8a5517a5c13c1ccbbd3a46c392468f6 Mon Sep 17 00:00:00 2001 From: morris Date: Fri, 9 Jul 2021 11:15:26 +0800 Subject: [PATCH] tiny_usb: rename Kconfig name 1. Renamed Kconfig file of tinyusb (distinguish tinyusb stack from usb peripheral) 2. bugfix/typofix/doc update of tinyusb --- components/esp_system/Kconfig | 5 +- components/tinyusb/CMakeLists.txt | 139 +++++----- components/tinyusb/Kconfig | 255 +++++++++--------- .../tinyusb/additions/include/tinyusb.h | 27 +- .../tinyusb/additions/include/tinyusb_types.h | 2 +- .../tinyusb/additions/include/tusb_config.h | 81 +++--- .../tinyusb/additions/include/tusb_tasks.h | 16 +- .../include_private/descriptors_control.h | 2 +- .../additions/src/descriptors_control.c | 52 ++-- components/tinyusb/additions/src/tinyusb.c | 68 ++--- .../tinyusb/additions/src/tusb_cdc_acm.c | 6 +- components/tinyusb/additions/src/tusb_tasks.c | 34 +-- .../tinyusb/additions/src/usb_descriptors.c | 32 +-- components/tinyusb/sdkconfig.rename | 22 ++ components/usb/CMakeLists.txt | 21 +- components/usb/Kconfig | 9 + examples/peripherals/usb/README.md | 23 ++ .../peripherals/usb/tusb_console/README.md | 73 ++--- .../usb/tusb_console/sdkconfig.defaults | 5 +- .../usb/tusb_sample_descriptor/README.md | 104 ++++--- .../main/tusb_sample_descriptor_main.c | 2 +- .../tusb_sample_descriptor/sdkconfig.defaults | 11 +- .../usb/tusb_serial_device/README.md | 88 +++--- .../main/tusb_serial_device_main.c | 4 +- .../usb/tusb_serial_device/sdkconfig.defaults | 5 +- 25 files changed, 589 insertions(+), 497 deletions(-) create mode 100644 components/tinyusb/sdkconfig.rename create mode 100644 components/usb/Kconfig create mode 100644 examples/peripherals/usb/README.md diff --git a/components/esp_system/Kconfig b/components/esp_system/Kconfig index 0c5faff0e9..509fbbb4aa 100644 --- a/components/esp_system/Kconfig +++ b/components/esp_system/Kconfig @@ -201,9 +201,8 @@ menu "ESP System Settings" bool "Default: UART0" config ESP_CONSOLE_USB_CDC bool "USB CDC" - # The naming is confusing: USB_ENABLED means that TinyUSB driver is enabled, not USB in general. - # && !USB_ENABLED is because the ROM CDC driver is currently incompatible with TinyUSB. - depends on (IDF_TARGET_ESP32S2 || IDF_TARGET_ESP32S3) && !USB_ENABLED + # && !TINY_USB is because the ROM CDC driver is currently incompatible with TinyUSB. + depends on (IDF_TARGET_ESP32S2 || IDF_TARGET_ESP32S3) && !TINY_USB config ESP_CONSOLE_USB_SERIAL_JTAG bool "USB Serial/JTAG Controller" select ESPTOOLPY_NO_STUB if IDF_TARGET_ESP32S3 #ESPTOOL-251 diff --git a/components/tinyusb/CMakeLists.txt b/components/tinyusb/CMakeLists.txt index a711abf598..b180c75e23 100644 --- a/components/tinyusb/CMakeLists.txt +++ b/components/tinyusb/CMakeLists.txt @@ -1,78 +1,81 @@ idf_build_get_property(target IDF_TARGET) -idf_component_register(REQUIRES esp_rom freertos vfs soc) -if(CONFIG_USB_ENABLED) +set(srcs) +set(includes_public) +set(includes_private) +set(compile_options) - if(target STREQUAL "esp32s3") - set(tusb_mcu "OPT_MCU_ESP32S3") - set(tusb_family "esp32sx") - elseif(target STREQUAL "esp32s2") - set(tusb_mcu "OPT_MCU_ESP32S2") - set(tusb_family "esp32sx") - else() - message("TinyUSB does not support ${target}.") - return() - endif() +if(CONFIG_TINYUSB) + if(target STREQUAL "esp32s3") + set(tusb_mcu "OPT_MCU_ESP32S3") + set(tusb_family "esp32sx") + elseif(target STREQUAL "esp32s2") + set(tusb_mcu "OPT_MCU_ESP32S2") + set(tusb_family "esp32sx") + else() + # CONFIG_TINYUSB dependency has been garanteed by Kconfig logic, + # So it's not possible that cmake goes here + message(FATAL_ERROR "TinyUSB is not support on ${target}.") + return() + endif() - ### variables ### - ################# - set(compile_options - "-DCFG_TUSB_MCU=${tusb_mcu}" - "-DCFG_TUSB_DEBUG=${CONFIG_USB_DEBUG_LEVEL}" - "-Wno-type-limits" # needed for the vanila tinyusb with turned off classes - ) + list(APPEND compile_options + "-DCFG_TUSB_MCU=${tusb_mcu}" + "-DCFG_TUSB_DEBUG=${CONFIG_TINYUSB_DEBUG_LEVEL}" + ) - idf_component_get_property(FREERTOS_ORIG_INCLUDE_PATH freertos - ORIG_INCLUDE_PATH) - set(includes_private - # tusb: - "${COMPONENT_DIR}/tinyusb/hw/bsp/" - "${COMPONENT_DIR}/tinyusb/src/" - "${COMPONENT_DIR}/tinyusb/src/device" - # espressif: - "${COMPONENT_DIR}/additions/include_private" - ) + idf_component_get_property(freertos_component_dir freertos COMPONENT_DIR) + + list(APPEND includes_private + "tinyusb/hw/bsp/" + "tinyusb/src/" + "tinyusb/src/device" + "additions/include_private" + ) + + list(APPEND includes_public + "tinyusb/src/" + "additions/include" + # The FreeRTOS API include convention in tinyusb is different from esp-idf + "${freertos_component_dir}/include/freertos" + ) - set(includes_public - # tusb: - "${FREERTOS_ORIG_INCLUDE_PATH}" - "${COMPONENT_DIR}/tinyusb/src/" - # espressif: - "${COMPONENT_DIR}/additions/include") - set(srcs - # espressif: - "${COMPONENT_DIR}/additions/src/descriptors_control.c" - "${COMPONENT_DIR}/additions/src/tinyusb.c" - "${COMPONENT_DIR}/additions/src/tusb_tasks.c" - "${COMPONENT_DIR}/additions/src/usb_descriptors.c" - # tusb: - "${COMPONENT_DIR}/tinyusb/src/portable/espressif/${tusb_family}/dcd_${tusb_family}.c" - "${COMPONENT_DIR}/tinyusb/src/class/cdc/cdc_device.c" - "${COMPONENT_DIR}/tinyusb/src/class/hid/hid_device.c" - "${COMPONENT_DIR}/tinyusb/src/class/midi/midi_device.c" - "${COMPONENT_DIR}/tinyusb/src/class/msc/msc_device.c" - "${COMPONENT_DIR}/tinyusb/src/class/vendor/vendor_device.c" - "${COMPONENT_DIR}/tinyusb/src/common/tusb_fifo.c" - "${COMPONENT_DIR}/tinyusb/src/device/usbd_control.c" - "${COMPONENT_DIR}/tinyusb/src/device/usbd.c" - "${COMPONENT_DIR}/tinyusb/src/tusb.c") - # cdc stuff if turned on - if(CONFIG_USB_CDC_ENABLED) list(APPEND srcs - "${COMPONENT_DIR}/additions/src/cdc.c" - "${COMPONENT_DIR}/additions/src/tusb_cdc_acm.c" - "${COMPONENT_DIR}/additions/src/tusb_console.c" - "${COMPONENT_DIR}/additions/src/vfs_tinyusb.c") - endif() + "tinyusb/src/portable/espressif/${tusb_family}/dcd_${tusb_family}.c" + "tinyusb/src/class/cdc/cdc_device.c" + "tinyusb/src/class/hid/hid_device.c" + "tinyusb/src/class/midi/midi_device.c" + "tinyusb/src/class/msc/msc_device.c" + "tinyusb/src/class/vendor/vendor_device.c" + "tinyusb/src/common/tusb_fifo.c" + "tinyusb/src/device/usbd_control.c" + "tinyusb/src/device/usbd.c" + "tinyusb/src/tusb.c" + "additions/src/descriptors_control.c" + "additions/src/tinyusb.c" + "additions/src/tusb_tasks.c" + "additions/src/usb_descriptors.c" + ) - ### tinyusb lib ### - ################### - add_library(tinyusb STATIC ${srcs}) - target_include_directories( - tinyusb - PUBLIC ${includes_public} - PRIVATE ${includes_private}) - target_compile_options(tinyusb PRIVATE ${compile_options}) - target_link_libraries(${COMPONENT_TARGET} INTERFACE tinyusb) + # when no builtin class driver is enabled, an uint8_t data compared with `BUILTIN_DRIVER_COUNT` will always be false + set_source_files_properties("tinyusb/src/device/usbd.c" PROPERTIES COMPILE_FLAGS "-Wno-type-limits") + if(CONFIG_TINYUSB_CDC_ENABLED) + list(APPEND srcs + "additions/src/cdc.c" + "additions/src/tusb_cdc_acm.c" + "additions/src/tusb_console.c" + "additions/src/vfs_tinyusb.c" + ) + endif() # CONFIG_TINYUSB_CDC_ENABLED +endif() # CONFIG_TINYUSB + +idf_component_register(SRCS ${srcs} + INCLUDE_DIRS ${includes_public} + PRIV_INCLUDE_DIRS ${includes_private} + PRIV_REQUIRES "vfs" + ) + +if(CONFIG_TINYUSB) + target_compile_options(${COMPONENT_LIB} PRIVATE ${compile_options}) endif() diff --git a/components/tinyusb/Kconfig b/components/tinyusb/Kconfig index 59cf899495..9e28a67713 100644 --- a/components/tinyusb/Kconfig +++ b/components/tinyusb/Kconfig @@ -1,150 +1,155 @@ -menu "TinyUSB" +menu "TinyUSB Stack" + visible if USB_OTG_SUPPORTED - config USB_ENABLED - bool "Enable TinyUSB driver" + config TINYUSB + bool "Use TinyUSB Stack" + depends on USB_OTG_SUPPORTED default n - depends on IDF_TARGET_ESP32S2 || IDF_TARGET_ESP32S3 - select FREERTOS_USE_AUTHENTIC_INCLUDE_PATHS help - Adds support for TinyUSB + Enable TinyUSB stack support. + Note that, esp-idf only uses the device stack provided by TinyUSB. - menu "USB task configuration" - depends on USB_ENABLED - - config USB_DO_NOT_CREATE_TASK - bool "Do not create a TinyUSB task" - default n + if TINYUSB + config TINYUSB_DEBUG_LEVEL + int "TinyUSB log level (0-3)" + default 0 + range 0 3 help - This option allows to not create the FreeRTOS task during the driver initialization. User will have - to handle TinyUSB events manually + Specify verbosity of TinyUSB log output. - config USB_TASK_PRIORITY - int "Set a priority of the TinyUSB task" - default 5 - depends on !USB_DO_NOT_CREATE_TASK - help - User can change the priority of the main task according the application needs + menu "TinyUSB task configuration" + config TINYUSB_NO_DEFAULT_TASK + bool "Do not create a TinyUSB task" + default n + help + This option allows to not create the FreeRTOS task during the driver initialization. + User will have to handle TinyUSB events manually. - endmenu + config TINYUSB_TASK_PRIORITY + int "TinyUSB task priority" + default 5 + depends on !TINYUSB_NO_DEFAULT_TASK + help + Set the priority of the default TinyUSB main task. - menu "Descriptor configuration" - depends on USB_ENABLED + config TINYUSB_TASK_STACK_SIZE + int "TinyUSB task stack size (bytes)" + default 4096 + depends on !TINYUSB_NO_DEFAULT_TASK + help + Set the stack size of the default TinyUSB main task. + endmenu - config USB_DESC_USE_ESPRESSIF_VID - bool "VID: Use an Espressif's default value" - default y - help - Long description + menu "Descriptor configuration" + config TINYUSB_DESC_USE_ESPRESSIF_VID + bool "VID: Use Espressif's vendor ID" + default y + help + Enable this option, USB device will use Espressif's vendor ID as its VID. + This is helpful at product develop stage. - config USB_DESC_CUSTOM_VID - hex "Custom VID value" - default 0x1234 - depends on !USB_DESC_USE_ESPRESSIF_VID - help - Custom Vendor ID + config TINYUSB_DESC_CUSTOM_VID + hex "VID: Custom vendor ID" + default 0x1234 + depends on !TINYUSB_DESC_USE_ESPRESSIF_VID + help + Custom Vendor ID. - config USB_DESC_USE_DEFAULT_PID - bool "PID: Use a default PID assigning" - default y - help - Default TinyUSB PID assigning uses values 0x4000...0x4007 + config TINYUSB_DESC_USE_DEFAULT_PID + bool "PID: Use a default PID assigned to TinyUSB" + default y + help + Default TinyUSB PID assigning uses values 0x4000...0x4007. - config USB_DESC_CUSTOM_PID - hex "Custom PID value" - default 0x5678 - depends on !USB_DESC_USE_DEFAULT_PID - help - Custom Product ID + config TINYUSB_DESC_CUSTOM_PID + hex "PID: Custom product ID" + default 0x5678 + depends on !TINYUSB_DESC_USE_DEFAULT_PID + help + Custom Product ID. - config USB_DESC_BCDDEVICE - hex "bcdDevice" - default 0x0100 - help - Version of the firmware of the USB device + config TINYUSB_DESC_BCD_DEVICE + hex "bcdDevice" + default 0x0100 + help + Version of the firmware of the USB device. - config USB_DESC_MANUFACTURER_STRING - string "Manufacturer" - default "Espressif Systems" - help - Name of the manufacturer of the USB device + config TINYUSB_DESC_MANUFACTURER_STRING + string "Manufacturer name" + default "Espressif Systems" + help + Name of the manufacturer of the USB device. - config USB_DESC_PRODUCT_STRING - string "Product" - default "Espressif Device" - help - Name of the USB device + config TINYUSB_DESC_PRODUCT_STRING + string "Product name" + default "Espressif Device" + help + Name of the USB device. - config USB_DESC_SERIAL_STRING - string "Serial string" - default "123456" - help - Specify serial number of the USB device + config TINYUSB_DESC_SERIAL_STRING + string "Serial string" + default "123456" + help + Serial number of the USB device. - config USB_DESC_CDC_STRING - string "CDC Device String" - default "Espressif CDC Device" - depends on USB_CDC_ENABLED - help - Specify name of the CDC device + config TINYUSB_DESC_CDC_STRING + depends on TINYUSB_CDC_ENABLED + string "CDC Device String" + default "Espressif CDC Device" + help + Name of the CDC device. - config USB_DESC_MSC_STRING - string "MSC Device String" - default "Espressif MSC Device" - depends on USB_MSC_ENABLED - help - Specify name of the MSC device + config TINYUSB_DESC_MSC_STRING + depends on TINYUSB_MSC_ENABLED + string "MSC Device String" + default "Espressif MSC Device" + help + Name of the MSC device. - config USB_DESC_HID_STRING - string "HID Device String" - default "Espressif HID Device" - depends on USB_HID_ENABLED - help - Specify name of the HID device + config TINYUSB_DESC_HID_STRING + depends on TINYUSB_HID_ENABLED + string "HID Device String" + default "Espressif HID Device" + help + Name of the HID device + endmenu # "Descriptor configuration" - endmenu + menu "Massive Storage Class (MSC)" + config TINYUSB_MSC_ENABLED + bool "Enable TinyUSB MSC feature" + default n + help + Enable TinyUSB MSC feature. - config USB_MSC_ENABLED - bool "Enable USB MSC TinyUSB driver" - default n - depends on USB_ENABLED - help - Enable USB MSC TinyUSB driver. + config TINYUSB_MSC_BUFSIZE + depends on TINYUSB_MSC_ENABLED + int "MSC FIFO size" + default 512 + help + MSC FIFO size, in bytes. + endmenu # "Massive Storage Class" - config USB_MSC_BUFSIZE - int "MSC FIFO size" - default 512 - depends on USB_MSC_ENABLED - help - MSC FIFO size + menu "Communication Device Class (CDC)" + config TINYUSB_CDC_ENABLED + bool "Enable TinyUSB CDC feature" + default n + help + Enable TinyUSB CDC feature. - config USB_CDC_ENABLED - bool "Enable USB Serial (CDC) TinyUSB driver" - default n - depends on USB_ENABLED - help - Enable USB Serial (CDC) TinyUSB driver. + config TINYUSB_CDC_RX_BUFSIZE + depends on TINYUSB_CDC_ENABLED + int "CDC FIFO size of RX channel" + default 64 + help + CDC FIFO size of RX channel. - config USB_CDC_RX_BUFSIZE - int "CDC FIFO size of RX" - default 64 - depends on USB_CDC_ENABLED - help - CDC FIFO size of RX + config TINYUSB_CDC_TX_BUFSIZE + depends on TINYUSB_CDC_ENABLED + int "CDC FIFO size of TX channel" + default 64 + help + CDC FIFO size of TX channel. + endmenu # "Communication Device Class" + endif # TINYUSB - config USB_CDC_TX_BUFSIZE - int "CDC FIFO size of TX" - default 64 - depends on USB_CDC_ENABLED - help - CDC FIFO size of TX - - - config USB_DEBUG_LEVEL - int "TinyUSB log level (0-3)" - default 0 - range 0 3 - depends on USB_ENABLED - help - Define amount of log output from TinyUSB - -endmenu +endmenu # "TinyUSB Stack" diff --git a/components/tinyusb/additions/include/tinyusb.h b/components/tinyusb/additions/include/tinyusb.h index 6704becf7d..aaa48fa725 100644 --- a/components/tinyusb/additions/include/tinyusb.h +++ b/components/tinyusb/additions/include/tinyusb.h @@ -27,9 +27,9 @@ extern "C" { /* tinyusb uses buffers with type of uint8_t[] but in our driver we are reading them as a 32-bit word */ -#if (CFG_TUD_ENDOINT0_SIZE < 4) -# define CFG_TUD_ENDOINT0_SIZE 4 -# warning "CFG_TUD_ENDOINT0_SIZE was too low and was set to 4" +#if (CFG_TUD_ENDPOINT0_SIZE < 4) +# define CFG_TUD_ENDPOINT0_SIZE 4 +# warning "CFG_TUD_ENDPOINT0_SIZE was too low and was set to 4" #endif #if TUSB_OPT_DEVICE_ENABLED @@ -72,13 +72,30 @@ extern "C" { */ typedef struct { tusb_desc_device_t *descriptor; /*!< Pointer to a device descriptor */ - char **string_descriptor; /*!< Pointer to an array of string descriptors */ + const char **string_descriptor; /*!< Pointer to an array of string descriptors */ bool external_phy; /*!< Should USB use an external PHY */ } tinyusb_config_t; +/** + * @brief This is an all-in-one helper function, including: + * 1. USB device driver initialization + * 2. Descriptors preparation + * 3. TinyUSB stack initialization + * 4. Creates and start a task to handle usb events + * + * @note Don't change Custom descriptor, but if it has to be done, + * Suggest to define as follows in order to match the Interface Association Descriptor (IAD): + * bDeviceClass = TUSB_CLASS_MISC, + * bDeviceSubClass = MISC_SUBCLASS_COMMON, + * + * @param config tinyusb stack specific configuration + * @retval ESP_ERR_INVALID_ARG Install driver and tinyusb stack failed because of invalid argument + * @retval ESP_FAIL Install driver and tinyusb stack failed because of internal error + * @retval ESP_OK Install driver and tinyusb stack successfully + */ esp_err_t tinyusb_driver_install(const tinyusb_config_t *config); -// TODO esp_err_t tinyusb_driver_uninstall(void); (IDF-1474) +// TODO esp_err_t tinyusb_driver_uninstall(void); (IDF-1474) #ifdef __cplusplus } diff --git a/components/tinyusb/additions/include/tinyusb_types.h b/components/tinyusb/additions/include/tinyusb_types.h index ad4a22de26..0f226f3fa1 100644 --- a/components/tinyusb/additions/include/tinyusb_types.h +++ b/components/tinyusb/additions/include/tinyusb_types.h @@ -25,7 +25,7 @@ typedef enum{ TINYUSB_USBDEV_0, } tinyusb_usbdev_t; -typedef char *tusb_desc_strarray_device_t[USB_STRING_DESCRIPTOR_ARRAY_SIZE]; +typedef const char *tusb_desc_strarray_device_t[USB_STRING_DESCRIPTOR_ARRAY_SIZE]; #ifdef __cplusplus } diff --git a/components/tinyusb/additions/include/tusb_config.h b/components/tinyusb/additions/include/tusb_config.h index 05509d5e4a..81ae270076 100644 --- a/components/tinyusb/additions/include/tusb_config.h +++ b/components/tinyusb/additions/include/tusb_config.h @@ -25,6 +25,7 @@ */ #pragma once + #include "tusb_option.h" #include "sdkconfig.h" @@ -32,11 +33,27 @@ extern "C" { #endif -/* */ -/* COMMON CONFIGURATION */ -/* */ +#ifndef CONFIG_TINYUSB_CDC_ENABLED +# define CONFIG_TINYUSB_CDC_ENABLED 0 +#endif -#define CFG_TUSB_RHPORT0_MODE OPT_MODE_DEVICE +#ifndef CONFIG_TINYUSB_MSC_ENABLED +# define CONFIG_TINYUSB_MSC_ENABLED 0 +#endif + +#ifndef CONFIG_TINYUSB_HID_ENABLED +# define CONFIG_TINYUSB_HID_ENABLED 0 +#endif + +#ifndef CONFIG_TINYUSB_MIDI_ENABLED +# define CONFIG_TINYUSB_MIDI_ENABLED 0 +#endif + +#ifndef CONFIG_TINYUSB_CUSTOM_CLASS_ENABLED +# define CONFIG_TINYUSB_CUSTOM_CLASS_ENABLED 0 +#endif + +#define CFG_TUSB_RHPORT0_MODE OPT_MODE_DEVICE | OPT_MODE_FULL_SPEED #define CFG_TUSB_OS OPT_OS_FREERTOS /* USB DMA on some MCUs can only access a specific SRAM region with restriction on alignment. @@ -51,55 +68,29 @@ extern "C" { #endif #ifndef CFG_TUSB_MEM_ALIGN -# define CFG_TUSB_MEM_ALIGN TU_ATTR_ALIGNED(4) +# define CFG_TUSB_MEM_ALIGN TU_ATTR_ALIGNED(4) #endif -/* */ -/* DRIVER CONFIGURATION */ -/* */ - -#define CFG_TUD_MAINTASK_SIZE 4096 -#define CFG_TUD_ENDOINT0_SIZE 64 +#ifndef CFG_TUD_ENDPOINT0_SIZE +#define CFG_TUD_ENDPOINT0_SIZE 64 +#endif // CDC FIFO size of TX and RX -#define CFG_TUD_CDC_RX_BUFSIZE CONFIG_USB_CDC_RX_BUFSIZE -#define CFG_TUD_CDC_TX_BUFSIZE CONFIG_USB_CDC_TX_BUFSIZE +#define CFG_TUD_CDC_RX_BUFSIZE CONFIG_TINYUSB_CDC_RX_BUFSIZE +#define CFG_TUD_CDC_TX_BUFSIZE CONFIG_TINYUSB_CDC_TX_BUFSIZE -// MSC Buffer size of Device Mass storage: -#define CFG_TUD_MSC_BUFSIZE CONFIG_USB_MSC_BUFSIZE +// MSC Buffer size of Device Mass storage +#define CFG_TUD_MSC_BUFSIZE CONFIG_TINYUSB_MSC_BUFSIZE // HID buffer size Should be sufficient to hold ID (if any) + Data -#define CFG_TUD_HID_BUFSIZE CONFIG_USB_HID_BUFSIZE +#define CFG_TUD_HID_BUFSIZE CONFIG_TINYUSB_HID_BUFSIZE -#define CFG_TUD_CDC CONFIG_USB_CDC_ENABLED -#define CFG_TUD_MSC CONFIG_USB_MSC_ENABLED -#define CFG_TUD_HID CONFIG_USB_HID_ENABLED -#define CFG_TUD_MIDI CONFIG_USB_MIDI_ENABLED -#define CFG_TUD_CUSTOM_CLASS CONFIG_USB_CUSTOM_CLASS_ENABLED - -/* */ -/* KCONFIG */ -/* */ - -#ifndef CONFIG_USB_CDC_ENABLED -# define CONFIG_USB_CDC_ENABLED 0 -#endif - -#ifndef CONFIG_USB_MSC_ENABLED -# define CONFIG_USB_MSC_ENABLED 0 -#endif - -#ifndef CONFIG_USB_HID_ENABLED -# define CONFIG_USB_HID_ENABLED 0 -#endif - -#ifndef CONFIG_USB_MIDI_ENABLED -# define CONFIG_USB_MIDI_ENABLED 0 -#endif - -#ifndef CONFIG_USB_CUSTOM_CLASS_ENABLED -# define CONFIG_USB_CUSTOM_CLASS_ENABLED 0 -#endif +// Enabled device class driver +#define CFG_TUD_CDC CONFIG_TINYUSB_CDC_ENABLED +#define CFG_TUD_MSC CONFIG_TINYUSB_MSC_ENABLED +#define CFG_TUD_HID CONFIG_TINYUSB_HID_ENABLED +#define CFG_TUD_MIDI CONFIG_TINYUSB_MIDI_ENABLED +#define CFG_TUD_CUSTOM_CLASS CONFIG_TINYUSB_CUSTOM_CLASS_ENABLED #ifdef __cplusplus } diff --git a/components/tinyusb/additions/include/tusb_tasks.h b/components/tinyusb/additions/include/tusb_tasks.h index 94ed4eafce..7f3209db51 100644 --- a/components/tinyusb/additions/include/tusb_tasks.h +++ b/components/tinyusb/additions/include/tusb_tasks.h @@ -16,26 +16,28 @@ #include "esp_err.h" - #ifdef __cplusplus extern "C" { #endif /** - * @brief This API starts a task with a wrapper function of tud_task and default task parameters. + * @brief This helper function creates and starts a task which wraps `tud_task()`. * - * The wrapper function basically wraps tud_task and some log. Default parameters: stack size and priority as configured, argument = NULL, - * not pinned to any core. + * The wrapper function basically wraps tud_task and some log. + * Default parameters: stack size and priority as configured, argument = NULL, not pinned to any core. * If you have more requirements for this task, you can create your own task which calls tud_task as the last step. * - * @return ESP_OK or ESP_FAIL + * @retval ESP_OK run tinyusb main task successfully + * @retval ESP_FAIL run tinyusb main task failed of internal error + * @retval ESP_ERR_INVALID_STATE tinyusb main task has been created before */ esp_err_t tusb_run_task(void); /** - * @brief Stops a FreeRTOS task + * @brief This helper function stops and destroys the task created by `tusb_run_task()` * - * @return ESP_OK or ESP_FAIL + * @retval ESP_OK stop and destory tinyusb main task successfully + * @retval ESP_ERR_INVALID_STATE tinyusb main task hasn't been created yet */ esp_err_t tusb_stop_task(void); diff --git a/components/tinyusb/additions/include_private/descriptors_control.h b/components/tinyusb/additions/include_private/descriptors_control.h index 4ef341932f..461ffa85e9 100644 --- a/components/tinyusb/additions/include_private/descriptors_control.h +++ b/components/tinyusb/additions/include_private/descriptors_control.h @@ -61,7 +61,7 @@ enum { }; bool tusb_desc_set; -void tusb_set_descriptor(tusb_desc_device_t *desc, char **str_desc); +void tusb_set_descriptor(tusb_desc_device_t *desc, const char **str_desc); tusb_desc_device_t *tusb_get_active_desc(void); char **tusb_get_active_str_desc(void); void tusb_clear_descriptor(void); diff --git a/components/tinyusb/additions/src/descriptors_control.c b/components/tinyusb/additions/src/descriptors_control.c index 659deeaf36..d7fbf0bda7 100644 --- a/components/tinyusb/additions/src/descriptors_control.c +++ b/components/tinyusb/additions/src/descriptors_control.c @@ -130,26 +130,40 @@ uint8_t const *tud_hid_descriptor_report_cb(void) // Driver functions // ============================================================================= -void tusb_set_descriptor(tusb_desc_device_t *desc, char **str_desc) +void tusb_set_descriptor(tusb_desc_device_t *dev_desc, const char **str_desc) { - ESP_LOGI(TAG, "Setting of a descriptor: \n" - ".bDeviceClass = %u\n" - ".bDeviceSubClass = %u,\n" - ".bDeviceProtocol = %u,\n" - ".bMaxPacketSize0 = %u,\n" - ".idVendor = 0x%08x,\n" - ".idProduct = 0x%08x,\n" - ".bcdDevice = 0x%08x,\n" - ".iManufacturer = 0x%02x,\n" - ".iProduct = 0x%02x,\n" - ".iSerialNumber = 0x%02x,\n" - ".bNumConfigurations = 0x%02x\n", - desc->bDeviceClass, desc->bDeviceSubClass, - desc->bDeviceProtocol, desc->bMaxPacketSize0, - desc->idVendor, desc->idProduct, desc->bcdDevice, - desc->iManufacturer, desc->iProduct, desc->iSerialNumber, - desc->bNumConfigurations); - s_descriptor = *desc; + ESP_LOGI(TAG, "\n" + "┌─────────────────────────────────┐\n" + "│ USB Device Descriptor Summary │\n" + "├───────────────────┬─────────────┤\n" + "│bDeviceClass │ %-4u │\n" + "├───────────────────┼─────────────┤\n" + "│bDeviceSubClass │ %-4u │\n" + "├───────────────────┼─────────────┤\n" + "│bDeviceProtocol │ %-4u │\n" + "├───────────────────┼─────────────┤\n" + "│bMaxPacketSize0 │ %-4u │\n" + "├───────────────────┼─────────────┤\n" + "│idVendor │ %-#10x │\n" + "├───────────────────┼─────────────┤\n" + "│idProduct │ %-#10x │\n" + "├───────────────────┼─────────────┤\n" + "│bcdDevice │ %-#10x │\n" + "├───────────────────┼─────────────┤\n" + "│iManufacturer │ %-#10x │\n" + "├───────────────────┼─────────────┤\n" + "│iProduct │ %-#10x │\n" + "├───────────────────┼─────────────┤\n" + "│iSerialNumber │ %-#10x │\n" + "├───────────────────┼─────────────┤\n" + "│bNumConfigurations │ %-#10x │\n" + "└───────────────────┴─────────────┘", + dev_desc->bDeviceClass, dev_desc->bDeviceSubClass, + dev_desc->bDeviceProtocol, dev_desc->bMaxPacketSize0, + dev_desc->idVendor, dev_desc->idProduct, dev_desc->bcdDevice, + dev_desc->iManufacturer, dev_desc->iProduct, dev_desc->iSerialNumber, + dev_desc->bNumConfigurations); + s_descriptor = *dev_desc; if (str_desc != NULL) { memcpy(s_str_descriptor, str_desc, diff --git a/components/tinyusb/additions/src/tinyusb.c b/components/tinyusb/additions/src/tinyusb.c index 9b709e2ab8..130a5884a0 100644 --- a/components/tinyusb/additions/src/tinyusb.c +++ b/components/tinyusb/additions/src/tinyusb.c @@ -12,12 +12,12 @@ // See the License for the specific language governing permissions and // limitations under the License. -#include "esp_log.h" -#include "esp_rom_gpio.h" +#include "sdkconfig.h" #include "driver/gpio.h" #include "driver/periph_ctrl.h" -#include "freertos/FreeRTOS.h" -#include "freertos/task.h" +#include "esp_log.h" +#include "esp_check.h" +#include "esp_rom_gpio.h" #include "hal/gpio_ll.h" #include "hal/usb_hal.h" #include "soc/gpio_periph.h" @@ -26,8 +26,6 @@ #include "descriptors_control.h" #include "tusb.h" #include "tusb_tasks.h" -#include "sdkconfig.h" -#include "esp_rom_gpio.h" const static char *TAG = "TinyUSB"; @@ -57,62 +55,30 @@ static void configure_pins(usb_hal_context_t *usb) } } - -/** - * @brief Initializes the tinyUSB driver. - * - * Note: Do not change any Custom descriptor, but - * if it used it is recomended to define: bDeviceClass = TUSB_CLASS_MISC, - * bDeviceSubClass = MISC_SUBCLASS_COMMON and bDeviceClass = TUSB_CLASS_MISC - * to match with Interface Association Descriptor (IAD) for CDC - * - * @param config if equal to NULL the default descriptor will be used - * @return esp_err_t Errors during the initialization - */ esp_err_t tinyusb_driver_install(const tinyusb_config_t *config) { - tusb_desc_device_t *descriptor; - int res; - char **string_descriptor; - ESP_LOGI(TAG, "Driver installation..."); - - periph_module_reset(PERIPH_USB_MODULE); + tusb_desc_device_t *dev_descriptor; + const char **string_descriptor; + ESP_RETURN_ON_FALSE(config, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); + // Enable APB CLK to USB peripheral periph_module_enable(PERIPH_USB_MODULE); - - // Hal init + periph_module_reset(PERIPH_USB_MODULE); + // Initialize HAL layer usb_hal_context_t hal = { .use_external_phy = config->external_phy }; usb_hal_init(&hal); configure_pins(&hal); - if (config->descriptor == NULL) { - descriptor = &descriptor_kconfig; - } else { - descriptor = config->descriptor; - } + dev_descriptor = config->descriptor ? config->descriptor : &descriptor_kconfig; + string_descriptor = config->string_descriptor ? config->string_descriptor : descriptor_str_kconfig; + tusb_set_descriptor(dev_descriptor, string_descriptor); - if (config->string_descriptor == NULL) { - string_descriptor = descriptor_str_kconfig; - } else { - string_descriptor = config->string_descriptor; - } - - tusb_set_descriptor(descriptor, - string_descriptor); - - if (!tusb_init()) { - ESP_LOGE(TAG, "Can't initialize the TinyUSB stack."); - return ESP_FAIL; - } -#if !CONFIG_USB_DO_NOT_CREATE_TASK - res = tusb_run_task(); - if (res != ESP_OK) { - ESP_LOGE(TAG, "Can't create the TinyUSB task."); - return res; - } + ESP_RETURN_ON_FALSE(tusb_init(), ESP_FAIL, TAG, "Init TinyUSB stack failed"); +#if !CONFIG_TINYUSB_NO_DEFAULT_TASK + ESP_RETURN_ON_ERROR(tusb_run_task(), TAG, "Run TinyUSB task failed"); #endif - ESP_LOGI(TAG, "Driver installed"); + ESP_LOGI(TAG, "TinyUSB Driver installed"); return ESP_OK; } diff --git a/components/tinyusb/additions/src/tusb_cdc_acm.c b/components/tinyusb/additions/src/tusb_cdc_acm.c index b29c483bca..f2e536c64b 100644 --- a/components/tinyusb/additions/src/tusb_cdc_acm.c +++ b/components/tinyusb/additions/src/tusb_cdc_acm.c @@ -103,7 +103,7 @@ void tud_cdc_rx_cb(uint8_t itf) while (tud_cdc_n_available(itf)) { int read_res = tud_cdc_n_read( itf, acm->rx_tfbuf, - CONFIG_USB_CDC_RX_BUFSIZE ); + CONFIG_TINYUSB_CDC_RX_BUFSIZE ); int res = xRingbufferSend(acm->rx_unread_buf, acm->rx_tfbuf, read_res, 0); @@ -312,7 +312,7 @@ esp_err_t tinyusb_cdcacm_write_flush(tinyusb_cdcacm_itf_t itf, uint32_t timeout_ if (!timeout_ticks) { // if no timeout - nonblocking mode int res = tud_cdc_n_write_flush(itf); if (!res) { - ESP_LOGW(TAG, "flush fauled (res: %d)", res); + ESP_LOGW(TAG, "flush failed (res: %d)", res); return ESP_FAIL; } else { if (tud_cdc_n_write_occupied(itf)) { @@ -396,7 +396,7 @@ esp_err_t tusb_cdc_acm_init(const tinyusb_config_cdcacm_t *cfg) return ESP_ERR_NO_MEM; } - acm->rx_tfbuf = malloc(CONFIG_USB_CDC_RX_BUFSIZE); + acm->rx_tfbuf = malloc(CONFIG_TINYUSB_CDC_RX_BUFSIZE); if (!acm->rx_tfbuf) { ESP_LOGE(TAG, "Creation buffer error"); free_obj(itf); diff --git a/components/tinyusb/additions/src/tusb_tasks.c b/components/tinyusb/additions/src/tusb_tasks.c index e70e69cf94..731247380a 100644 --- a/components/tinyusb/additions/src/tusb_tasks.c +++ b/components/tinyusb/additions/src/tusb_tasks.c @@ -12,13 +12,13 @@ // See the License for the specific language governing permissions and // limitations under the License. -#include "esp_log.h" +#include "sdkconfig.h" #include "freertos/FreeRTOS.h" #include "freertos/task.h" -#include "hal/usb_hal.h" +#include "esp_log.h" +#include "esp_check.h" #include "tinyusb.h" #include "tusb_tasks.h" -#include "sdkconfig.h" const static char *TAG = "tusb_tsk"; static TaskHandle_t s_tusb_tskh; @@ -34,29 +34,21 @@ static void tusb_device_task(void *arg) } } - esp_err_t tusb_run_task(void) { + // This function is not garanteed to be thread safe, if invoked multiple times without calling `tusb_stop_task`, will cause memory leak + // doing a sanity check anyway + ESP_RETURN_ON_FALSE(!s_tusb_tskh, ESP_ERR_INVALID_STATE, TAG, "TinyUSB main task already started"); // Create a task for tinyusb device stack: - xTaskCreate(tusb_device_task, "tinyUSB: main task", CFG_TUD_MAINTASK_SIZE, NULL, CONFIG_USB_TASK_PRIORITY, &s_tusb_tskh); - if (!s_tusb_tskh) { - return ESP_FAIL; - } else { - return ESP_OK; - } + xTaskCreate(tusb_device_task, "TinyUSB", CONFIG_TINYUSB_TASK_STACK_SIZE, NULL, CONFIG_TINYUSB_TASK_PRIORITY, &s_tusb_tskh); + ESP_RETURN_ON_FALSE(s_tusb_tskh, ESP_FAIL, TAG, "create TinyUSB main task failed"); + return ESP_OK; } esp_err_t tusb_stop_task(void) { - if ( s_tusb_tskh != NULL ) { - vTaskDelete(s_tusb_tskh); - } else { - ESP_LOGE(TAG, "tinyusb task is not started"); - return ESP_FAIL; - } - if (s_tusb_tskh) { - return ESP_FAIL; - } else { - return ESP_OK; - } + ESP_RETURN_ON_FALSE(s_tusb_tskh, ESP_ERR_INVALID_STATE, TAG, "TinyUSB main task not started yet"); + vTaskDelete(s_tusb_tskh); + s_tusb_tskh = NULL; + return ESP_OK; } diff --git a/components/tinyusb/additions/src/usb_descriptors.c b/components/tinyusb/additions/src/usb_descriptors.c index 98491e5f00..3b24337f83 100644 --- a/components/tinyusb/additions/src/usb_descriptors.c +++ b/components/tinyusb/additions/src/usb_descriptors.c @@ -35,7 +35,7 @@ tusb_desc_device_t descriptor_tinyusb = { .bDeviceProtocol = 0x00, #endif - .bMaxPacketSize0 = CFG_TUD_ENDOINT0_SIZE, + .bMaxPacketSize0 = CFG_TUD_ENDPOINT0_SIZE, .idVendor = 0xCafe, .idProduct = USB_TUSB_PID, @@ -78,21 +78,21 @@ tusb_desc_device_t descriptor_kconfig = { .bDeviceProtocol = 0x00, #endif - .bMaxPacketSize0 = CFG_TUD_ENDOINT0_SIZE, + .bMaxPacketSize0 = CFG_TUD_ENDPOINT0_SIZE, -#if CONFIG_USB_DESC_USE_ESPRESSIF_VID +#if CONFIG_TINYUSB_DESC_USE_ESPRESSIF_VID .idVendor = USB_ESPRESSIF_VID, #else - .idVendor = CONFIG_USB_DESC_CUSTOM_VID, + .idVendor = CONFIG_TINYUSB_DESC_CUSTOM_VID, #endif -#if CONFIG_USB_DESC_USE_DEFAULT_PID +#if CONFIG_TINYUSB_DESC_USE_DEFAULT_PID .idProduct = USB_TUSB_PID, #else - .idProduct = CONFIG_USB_DESC_CUSTOM_PID, + .idProduct = CONFIG_TINYUSB_DESC_CUSTOM_PID, #endif - .bcdDevice = CONFIG_USB_DESC_BCDDEVICE, + .bcdDevice = CONFIG_TINYUSB_DESC_BCD_DEVICE, .iManufacturer = 0x01, .iProduct = 0x02, @@ -104,24 +104,24 @@ tusb_desc_device_t descriptor_kconfig = { tusb_desc_strarray_device_t descriptor_str_kconfig = { // array of pointer to string descriptors (char[]){0x09, 0x04}, // 0: is supported language is English (0x0409) - CONFIG_USB_DESC_MANUFACTURER_STRING, // 1: Manufacturer - CONFIG_USB_DESC_PRODUCT_STRING, // 2: Product - CONFIG_USB_DESC_SERIAL_STRING, // 3: Serials, should use chip ID + CONFIG_TINYUSB_DESC_MANUFACTURER_STRING, // 1: Manufacturer + CONFIG_TINYUSB_DESC_PRODUCT_STRING, // 2: Product + CONFIG_TINYUSB_DESC_SERIAL_STRING, // 3: Serials, should use chip ID -#if CONFIG_USB_CDC_ENABLED - CONFIG_USB_DESC_CDC_STRING, // 4: CDC Interface +#if CONFIG_TINYUSB_CDC_ENABLED + CONFIG_TINYUSB_DESC_CDC_STRING, // 4: CDC Interface #else "", #endif -#if CONFIG_USB_MSC_ENABLED - CONFIG_USB_DESC_MSC_STRING, // 5: MSC Interface +#if CONFIG_TINYUSB_MSC_ENABLED + CONFIG_TINYUSB_DESC_MSC_STRING, // 5: MSC Interface #else "", #endif -#if CONFIG_USB_HID_ENABLED - CONFIG_USB_DESC_HID_STRING // 6: HIDs +#if CONFIG_TINYUSB_HID_ENABLED + CONFIG_TINYUSB_DESC_HID_STRING // 6: HIDs #else "", #endif diff --git a/components/tinyusb/sdkconfig.rename b/components/tinyusb/sdkconfig.rename new file mode 100644 index 0000000000..6aea8579ac --- /dev/null +++ b/components/tinyusb/sdkconfig.rename @@ -0,0 +1,22 @@ +# sdkconfig replacement configurations for deprecated options formatted as +# CONFIG_DEPRECATED_OPTION CONFIG_NEW_OPTION +CONFIG_USB_ENABLED CONFIG_TINYUSB +CONFIG_USB_DO_NOT_CREATE_TASK CONFIG_TINYUSB_NO_DEFAULT_TASK +CONFIG_USB_TASK_PRIORITY CONFIG_TINYUSB_TASK_PRIORITY +CONFIG_USB_DESC_USE_ESPRESSIF_VID CONFIG_TINYUSB_DESC_USE_ESPRESSIF_VID +CONFIG_USB_DESC_CUSTOM_VID CONFIG_TINYUSB_DESC_CUSTOM_VID +CONFIG_USB_DESC_USE_DEFAULT_PID CONFIG_TINYUSB_DESC_USE_DEFAULT_PID +CONFIG_USB_DESC_CUSTOM_PID CONFIG_TINYUSB_DESC_CUSTOM_PID +CONFIG_USB_DESC_BCDDEVICE CONFIG_TINYUSB_DESC_BCD_DEVICE +CONFIG_USB_DESC_MANUFACTURER_STRING CONFIG_TINYUSB_DESC_MANUFACTURER_STRING +CONFIG_USB_DESC_PRODUCT_STRING CONFIG_TINYUSB_DESC_PRODUCT_STRING +CONFIG_USB_DESC_SERIAL_STRING CONFIG_TINYUSB_DESC_SERIAL_STRING +CONFIG_USB_DESC_CDC_STRING CONFIG_TINYUSB_DESC_CDC_STRING +CONFIG_USB_DESC_MSC_STRING CONFIG_TINYUSB_DESC_MSC_STRING +CONFIG_USB_DESC_HID_STRING CONFIG_TINYUSB_DESC_HID_STRING +CONFIG_USB_MSC_ENABLED CONFIG_TINYUSB_MSC_ENABLED +CONFIG_USB_MSC_BUFSIZE CONFIG_TINYUSB_MSC_BUFSIZE +CONFIG_USB_CDC_ENABLED CONFIG_TINYUSB_CDC_ENABLED +CONFIG_USB_CDC_RX_BUFSIZE CONFIG_TINYUSB_CDC_RX_BUFSIZE +CONFIG_USB_CDC_TX_BUFSIZE CONFIG_TINYUSB_CDC_TX_BUFSIZE +CONFIG_USB_DEBUG_LEVEL CONFIG_TINYUSB_DEBUG_LEVEL diff --git a/components/usb/CMakeLists.txt b/components/usb/CMakeLists.txt index 0145f81e2a..20d143ea6e 100644 --- a/components/usb/CMakeLists.txt +++ b/components/usb/CMakeLists.txt @@ -1,11 +1,16 @@ -idf_build_get_property(target IDF_TARGET) +set(srcs) +set(include) +set(priv_include) +set(priv_require) -#USB Host is currently only supported on ESP32-S2, ESP32S3 chips -if(NOT "${target}" MATCHES "^esp32s[2-3]") - return() +if(CONFIG_USB_OTG_SUPPORTED) + list(APPEND srcs "hcd.c") + list(APPEND priv_include "private_include") + list(APPEND priv_require "hal" "driver") endif() -idf_component_register(SRCS "hcd.c" - INCLUDE_DIRS "" - PRIV_INCLUDE_DIRS "private_include" - PRIV_REQUIRES hal driver) +idf_component_register(SRCS ${srcs} + INCLUDE_DIRS ${include} + PRIV_INCLUDE_DIRS ${priv_include} + PRIV_REQUIRES ${priv_require} + ) diff --git a/components/usb/Kconfig b/components/usb/Kconfig new file mode 100644 index 0000000000..2be5c9da6b --- /dev/null +++ b/components/usb/Kconfig @@ -0,0 +1,9 @@ +menu "USB-OTG" + visible if IDF_TARGET_ESP32S2 || IDF_TARGET_ESP32S3 + + # Invisible item, enabled when USB_OTG peripheral does exist + config USB_OTG_SUPPORTED + bool + default y if IDF_TARGET_ESP32S2 || IDF_TARGET_ESP32S3 + +endmenu diff --git a/examples/peripherals/usb/README.md b/examples/peripherals/usb/README.md new file mode 100644 index 0000000000..2d23a497d7 --- /dev/null +++ b/examples/peripherals/usb/README.md @@ -0,0 +1,23 @@ +# USB-OTG Examples + +See the [README.md](../README.md) file in the upper level [examples](../) directory for more information about examples. + +## Common Pin Assignments + +Pin assignment is only needed for ESP chips that have an USB-OTG peripheral. +If your board doesn't have a USB connector connected to the USB-OTG dedicated GPIOs, you may have to DIY a cable and connect **D+** and **D-** to the pins listed below. + +``` +ESP BOARD USB CONNECTOR (type A) + -- + | || VCC +[USBPHY_DM_NUM] ------> | || D- +[USBPHY_DP_NUM] ------> | || D+ + | || GND + -- +``` +Refer to `soc/usb_pins.h` to find the real GPIO number of **USBPHY_DP_NUM** and **USBPHY_DM_NUM**. + +| | USB_DP | USB_DM | +| ----------- | ------ | ------ | +| ESP32-S2/S3 | GPIO20 | GPIO19 | diff --git a/examples/peripherals/usb/tusb_console/README.md b/examples/peripherals/usb/tusb_console/README.md index 4b656c0147..0c263df0b4 100644 --- a/examples/peripherals/usb/tusb_console/README.md +++ b/examples/peripherals/usb/tusb_console/README.md @@ -1,11 +1,11 @@ -| Supported Targets | ESP32-S2 | -| ----------------- | -------- | +| Supported Targets | ESP32-S2 | ESP32-S3 | +| ----------------- | -------- | -------- | # TinyUSB Sample Descriptor (See the README.md file in the upper level 'examples' directory for more information about examples.) -This example shows how to set up ESP32-S2 chip to get log output via Serial Device connection +This example shows how to set up ESP chip to get log output via Serial Device connection. As a USB stack, a TinyUSB component is used. @@ -13,21 +13,11 @@ As a USB stack, a TinyUSB component is used. ### Hardware Required -- Any board with the ESP32-S2 chip with USB connectors or with exposed USB's D+ and D- (DATA+/DATA-) pins. +Any ESP boards that have USB-OTG supported. -If the board has no USB connector, but has the pins connect pins directly to the host (e.g. with DIY cable from any USB connection cable) +#### Pin Assignment -``` -ESP32-S2 BOARD USB CONNECTOR (type A) - -- - | || VCC - [GPIO 19] --------> | || D- - [GPIO 20] --------> | || D+ - | || GND - -- -``` - -You can also use power from the USB connector. +See common pin assignments for USB Device examples from [upper level](../README.md#common-pin-assignments). ### Build and Flash @@ -54,24 +44,36 @@ Note: if you want to send data to the target see how to implement it via `tud_cd After the flashing you should see the output at idf monitor: ``` -I (340) example: USB initialization -I (340) TinyUSB: Driver installation... -I (340) TinyUSB - Descriptors Control: Setting of a descriptor: -.bDeviceClass = 239 -.bDeviceSubClass = 2, -.bDeviceProtocol = 1, -.bMaxPacketSize0 = 64, -.idVendor = 0x0000303a, -.idProduct = 0x00004001, -.bcdDevice = 0x00000100, -.iManufacturer = 0x01, -.iProduct = 0x02, -.iSerialNumber = 0x03, -.bNumConfigurations = 0x01 - -I (373) TinyUSB: Driver installed -I (373) example: USB initialization DONE -I (383) example: log -> UART +I (288) example: USB initialization +I (288) tusb_desc: +┌─────────────────────────────────┐ +│ USB Device Descriptor Summary │ +├───────────────────┬─────────────┤ +│bDeviceClass │ 239 │ +├───────────────────┼─────────────┤ +│bDeviceSubClass │ 2 │ +├───────────────────┼─────────────┤ +│bDeviceProtocol │ 1 │ +├───────────────────┼─────────────┤ +│bMaxPacketSize0 │ 64 │ +├───────────────────┼─────────────┤ +│idVendor │ 0x303a │ +├───────────────────┼─────────────┤ +│idProduct │ 0x4001 │ +├───────────────────┼─────────────┤ +│bcdDevice │ 0x100 │ +├───────────────────┼─────────────┤ +│iManufacturer │ 0x1 │ +├───────────────────┼─────────────┤ +│iProduct │ 0x2 │ +├───────────────────┼─────────────┤ +│iSerialNumber │ 0x3 │ +├───────────────────┼─────────────┤ +│bNumConfigurations │ 0x1 │ +└───────────────────┴─────────────┘ +I (458) TinyUSB: TinyUSB Driver installed +I (468) example: USB initialization DONE +I (468) example: log -> UART example: print -> stdout example: print -> stderr ... @@ -80,8 +82,7 @@ example: print -> stderr Other log will be printed to USB: ``` -I (5382) example: log -> USB +I (3478) example: log -> USB example: print -> stdout example: print -> stderr -... ``` diff --git a/examples/peripherals/usb/tusb_console/sdkconfig.defaults b/examples/peripherals/usb/tusb_console/sdkconfig.defaults index 67c45c3f45..cb49d0ea40 100644 --- a/examples/peripherals/usb/tusb_console/sdkconfig.defaults +++ b/examples/peripherals/usb/tusb_console/sdkconfig.defaults @@ -1,3 +1,2 @@ -CONFIG_IDF_TARGET="esp32s2" -CONFIG_USB_ENABLED=y -CONFIG_USB_CDC_ENABLED=y +CONFIG_TINYUSB=y +CONFIG_TINYUSB_CDC_ENABLED=y diff --git a/examples/peripherals/usb/tusb_sample_descriptor/README.md b/examples/peripherals/usb/tusb_sample_descriptor/README.md index 6b463f195d..35dce6b572 100644 --- a/examples/peripherals/usb/tusb_sample_descriptor/README.md +++ b/examples/peripherals/usb/tusb_sample_descriptor/README.md @@ -1,11 +1,11 @@ -| Supported Targets | ESP32-S2 | -| ----------------- | -------- | +| Supported Targets | ESP32-S2 | ESP32-S3 | +| ----------------- | -------- | -------- | # TinyUSB Sample Descriptor (See the README.md file in the upper level 'examples' directory for more information about examples.) -This example is demonstrating how to set up ESP32-S2 chip to work as a Generic USB Device with a user-defined descriptor. You can specify a manufacturer, device's name, ID and other USB-devices parameters responsible for identification by host. +This example is demonstrating how to set up ESP chip to work as a Generic USB Device with a user-defined descriptor. You can specify a manufacturer, device's name, ID and other USB-devices parameters responsible for identification by host. As a USB stack, a TinyUSB component is used. @@ -13,21 +13,11 @@ As a USB stack, a TinyUSB component is used. ### Hardware Required -- Any board with the ESP32-S2 chip with USB connectors or with exposed USB's D+ and D- (DATA+/DATA-) pins. +Any ESP boards that have USB-OTG supported. -If the board has no USB connector, but has the pins connect pins directly to the host (e.g. with DIY cable from any USB connection cable) +#### Pin Assignment -``` -ESP32-S2 BOARD USB CONNECTOR (type A) - -- - | || VCC - [GPIO 19] --------> | || D- - [GPIO 20] --------> | || D+ - | || GND - -- -``` - -You can also use power from the USB connector. +See common pin assignments for USB Device examples from [upper level](../README.md#common-pin-assignments). ### Configure the project @@ -35,7 +25,7 @@ There are two ways to set up a descriptor - using Menuconfig tool and in-code #### In-code setting up -For the manual descriptor's configuration use the default example's settings and modify `tusb_sample_descriptor.c` according to your needs +For the manual descriptor configuration use the default example's settings and modify `my_descriptor` in [source code](tusb_sample_descriptor_main.c) according to your needs #### Menuconfig @@ -66,20 +56,68 @@ See the Getting Started Guide for full steps to configure and use ESP-IDF to bui After the flashing you should see the output: ``` -I (349) TinyUSB: Driver installation... -I (349) TinyUSB - Descriptors Control: Setting of a descriptor: -.bDeviceClass = 0 -.bDeviceSubClass = 0, -.bDeviceProtocol = 0, -.bMaxPacketSize0 = 64, -.idVendor = 0x0000303a, -.idProduct = 0x00003000, -.bcdDevice = 0x00000101, -.iManufacturer = 0x01, -.iProduct = 0x02, -.iSerialNumber = 0x03, -.bNumConfigurations = 0x01 - -I (389) TinyUSB: Driver installed -I (389) example: USB initialization DONE +I (287) example: USB initialization +I (287) tusb_desc: +┌─────────────────────────────────┐ +│ USB Device Descriptor Summary │ +├───────────────────┬─────────────┤ +│bDeviceClass │ 0 │ +├───────────────────┼─────────────┤ +│bDeviceSubClass │ 0 │ +├───────────────────┼─────────────┤ +│bDeviceProtocol │ 0 │ +├───────────────────┼─────────────┤ +│bMaxPacketSize0 │ 64 │ +├───────────────────┼─────────────┤ +│idVendor │ 0x303a │ +├───────────────────┼─────────────┤ +│idProduct │ 0x3000 │ +├───────────────────┼─────────────┤ +│bcdDevice │ 0x101 │ +├───────────────────┼─────────────┤ +│iManufacturer │ 0x1 │ +├───────────────────┼─────────────┤ +│iProduct │ 0x2 │ +├───────────────────┼─────────────┤ +│iSerialNumber │ 0x3 │ +├───────────────────┼─────────────┤ +│bNumConfigurations │ 0x1 │ +└───────────────────┴─────────────┘ +I (457) TinyUSB: TinyUSB Driver installed +I (467) example: USB initialization DONE +``` + +From PC, running `lsusb -v`, you should find the device's descriptor like: +``` +Bus 001 Device 007: ID 303a:3000 I My Custom Device +Device Descriptor: + bLength 18 + bDescriptorType 1 + bcdUSB 2.00 + bDeviceClass 0 + bDeviceSubClass 0 + bDeviceProtocol 0 + bMaxPacketSize0 64 + idVendor 0x303a + idProduct 0x3000 + bcdDevice 1.01 + iManufacturer 1 I + iProduct 2 My Custom Device + iSerial 3 012-345 + bNumConfigurations 1 + Configuration Descriptor: + bLength 9 + bDescriptorType 2 + wTotalLength 0x0009 + bNumInterfaces 0 + bConfigurationValue 1 + iConfiguration 0 + bmAttributes 0xa0 + (Bus Powered) + Remote Wakeup + MaxPower 100mA +can't get device qualifier: Resource temporarily unavailable +can't get debug descriptor: Resource temporarily unavailable +Device Status: 0x0000 + (Bus Powered) ``` diff --git a/examples/peripherals/usb/tusb_sample_descriptor/main/tusb_sample_descriptor_main.c b/examples/peripherals/usb/tusb_sample_descriptor/main/tusb_sample_descriptor_main.c index c0923529af..edd76c4926 100644 --- a/examples/peripherals/usb/tusb_sample_descriptor/main/tusb_sample_descriptor_main.c +++ b/examples/peripherals/usb/tusb_sample_descriptor/main/tusb_sample_descriptor_main.c @@ -29,7 +29,7 @@ void app_main(void) .bDescriptorType = TUSB_DESC_DEVICE, .bcdUSB = 0x0200, // USB version. 0x0200 means version 2.0 .bDeviceClass = TUSB_CLASS_UNSPECIFIED, - .bMaxPacketSize0 = CFG_TUD_ENDOINT0_SIZE, + .bMaxPacketSize0 = CFG_TUD_ENDPOINT0_SIZE, .idVendor = 0x303A, .idProduct = 0x3000, diff --git a/examples/peripherals/usb/tusb_sample_descriptor/sdkconfig.defaults b/examples/peripherals/usb/tusb_sample_descriptor/sdkconfig.defaults index 4d3be63997..9e66e7cc08 100644 --- a/examples/peripherals/usb/tusb_sample_descriptor/sdkconfig.defaults +++ b/examples/peripherals/usb/tusb_sample_descriptor/sdkconfig.defaults @@ -1,6 +1,5 @@ -CONFIG_IDF_TARGET="esp32s2" -CONFIG_USB_ENABLED=y -CONFIG_USB_DESC_USE_ESPRESSIF_VID=n -CONFIG_USB_DESC_CUSTOM_VID=0x303A -CONFIG_USB_DESC_USE_DEFAULT_PID=n -CONFIG_USB_DESC_CUSTOM_PID=0x3000 +CONFIG_TINYUSB=y +CONFIG_TINYUSB_DESC_USE_ESPRESSIF_VID=n +CONFIG_TINYUSB_DESC_CUSTOM_VID=0x303A +CONFIG_TINYUSB_DESC_USE_DEFAULT_PID=n +CONFIG_TINYUSB_DESC_CUSTOM_PID=0x3000 diff --git a/examples/peripherals/usb/tusb_serial_device/README.md b/examples/peripherals/usb/tusb_serial_device/README.md index 1f7943df98..371a0f1403 100644 --- a/examples/peripherals/usb/tusb_serial_device/README.md +++ b/examples/peripherals/usb/tusb_serial_device/README.md @@ -1,11 +1,11 @@ -| Supported Targets | ESP32-S2 | -| ----------------- | -------- | +| Supported Targets | ESP32-S2 | ESP32-S3 | +| ----------------- | -------- | -------- | # TinyUSB Sample Descriptor (See the README.md file in the upper level 'examples' directory for more information about examples.) -This example shows how to set up ESP32-S2 chip to work as a USB Serial Device. +This example shows how to set up ESP chip to work as a USB Serial Device. As a USB stack, a TinyUSB component is used. @@ -13,21 +13,11 @@ As a USB stack, a TinyUSB component is used. ### Hardware Required -- Any board with the ESP32-S2 chip with USB connectors or with exposed USB's D+ and D- (DATA+/DATA-) pins. +Any ESP boards that have USB-OTG supported. -If the board has no USB connector, but has the pins connect pins directly to the host (e.g. with DIY cable from any USB connection cable) +#### Pin Assignment -``` -ESP32-S2 BOARD USB CONNECTOR (type A) - -- - | || VCC - [GPIO 19] --------> | || D- - [GPIO 20] --------> | || D+ - | || GND - -- -``` - -You can also use power from the USB connector. +See common pin assignments for USB Device examples from [upper level](../README.md#common-pin-assignments). ### Build and Flash @@ -43,37 +33,55 @@ idf.py -p PORT flash monitor See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. -## Serial Connection - -After program's start and getting of the message of readiness (`Serial device is ready to connect`) you can connect to the board using any serial port terminal application (e.g. CoolTerm). - ## Example Output After the flashing you should see the output: ``` -I (346) example: USB initialization -I (346) TinyUSB: Driver installation... -I (346) TinyUSB - Descriptors Control: Setting of a descriptor: -.bDeviceClass = 239 -.bDeviceSubClass = 2, -.bDeviceProtocol = 1, -.bMaxPacketSize0 = 64, -.idVendor = 0x0000303a, -.idProduct = 0x00004001, -.bcdDevice = 0x00000100, -.iManufacturer = 0x01, -.iProduct = 0x02, -.iSerialNumber = 0x03, -.bNumConfigurations = 0x01 - -I (362) TinyUSB: Driver installed -I (362) example: USB initialization DONE -I (922) example: Line state changed! dtr:0, rst:0 +I (285) example: USB initialization +I (285) tusb_desc: +┌─────────────────────────────────┐ +│ USB Device Descriptor Summary │ +├───────────────────┬─────────────┤ +│bDeviceClass │ 239 │ +├───────────────────┼─────────────┤ +│bDeviceSubClass │ 2 │ +├───────────────────┼─────────────┤ +│bDeviceProtocol │ 1 │ +├───────────────────┼─────────────┤ +│bMaxPacketSize0 │ 64 │ +├───────────────────┼─────────────┤ +│idVendor │ 0x303a │ +├───────────────────┼─────────────┤ +│idProduct │ 0x4001 │ +├───────────────────┼─────────────┤ +│bcdDevice │ 0x100 │ +├───────────────────┼─────────────┤ +│iManufacturer │ 0x1 │ +├───────────────────┼─────────────┤ +│iProduct │ 0x2 │ +├───────────────────┼─────────────┤ +│iSerialNumber │ 0x3 │ +├───────────────────┼─────────────┤ +│bNumConfigurations │ 0x1 │ +└───────────────────┴─────────────┘ +I (455) TinyUSB: TinyUSB Driver installed +I (465) example: USB initialization DONE ``` -Let's try to send a string "espressif" and get the return string in your console on PC: +Connect to the serial port (e.g. on Linux, it should be `/dev/ttyACM0`) by any terminal application (e.g. `picocom /dev/ttyACM0`), typing a string "espressif" and you will get the exactly same string returned. + +The monitor tool will also print the communication process: ``` -I (18346) example: Got data (9 bytes): espressif +I (146186) example: Line state changed! dtr:1, rst:1 +I (147936) example: Got data (1 bytes): e +I (148136) example: Got data (1 bytes): s +I (148336) example: Got data (1 bytes): p +I (148416) example: Got data (1 bytes): r +I (148446) example: Got data (1 bytes): e +I (148676) example: Got data (1 bytes): s +I (148836) example: Got data (1 bytes): s +I (148956) example: Got data (1 bytes): i +I (149066) example: Got data (1 bytes): f ``` diff --git a/examples/peripherals/usb/tusb_serial_device/main/tusb_serial_device_main.c b/examples/peripherals/usb/tusb_serial_device/main/tusb_serial_device_main.c index 8e1d74e3b8..bafc064c9d 100644 --- a/examples/peripherals/usb/tusb_serial_device/main/tusb_serial_device_main.c +++ b/examples/peripherals/usb/tusb_serial_device/main/tusb_serial_device_main.c @@ -20,7 +20,7 @@ #include "sdkconfig.h" static const char *TAG = "example"; -static uint8_t buf[CONFIG_USB_CDC_RX_BUFSIZE + 1]; +static uint8_t buf[CONFIG_TINYUSB_CDC_RX_BUFSIZE + 1]; void tinyusb_cdc_rx_callback(int itf, cdcacm_event_t *event) { @@ -28,7 +28,7 @@ void tinyusb_cdc_rx_callback(int itf, cdcacm_event_t *event) size_t rx_size = 0; /* read */ - esp_err_t ret = tinyusb_cdcacm_read(itf, buf, CONFIG_USB_CDC_RX_BUFSIZE, &rx_size); + esp_err_t ret = tinyusb_cdcacm_read(itf, buf, CONFIG_TINYUSB_CDC_RX_BUFSIZE, &rx_size); if (ret == ESP_OK) { buf[rx_size] = '\0'; ESP_LOGI(TAG, "Got data (%d bytes): %s", rx_size, buf); diff --git a/examples/peripherals/usb/tusb_serial_device/sdkconfig.defaults b/examples/peripherals/usb/tusb_serial_device/sdkconfig.defaults index 67c45c3f45..cb49d0ea40 100644 --- a/examples/peripherals/usb/tusb_serial_device/sdkconfig.defaults +++ b/examples/peripherals/usb/tusb_serial_device/sdkconfig.defaults @@ -1,3 +1,2 @@ -CONFIG_IDF_TARGET="esp32s2" -CONFIG_USB_ENABLED=y -CONFIG_USB_CDC_ENABLED=y +CONFIG_TINYUSB=y +CONFIG_TINYUSB_CDC_ENABLED=y