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/hal/esp32s3/include/hal/usb_ll.h b/components/hal/esp32s3/include/hal/usb_ll.h index 2be637f55c..81950021d2 100644 --- a/components/hal/esp32s3/include/hal/usb_ll.h +++ b/components/hal/esp32s3/include/hal/usb_ll.h @@ -17,17 +17,28 @@ #include "soc/system_reg.h" #include "soc/gpio_sig_map.h" #include "soc/usb_periph.h" +#include "soc/rtc_cntl_struct.h" static inline void usb_ll_int_phy_enable(void) { USB_WRAP.otg_conf.pad_enable = 1; + // USB_OTG use internal PHY USB_WRAP.otg_conf.phy_sel = 0; + // phy_sel is controlled by the following register value + RTCCNTL.usb_conf.sw_hw_usb_phy_sel = 1; + // phy_sel=sw_usb_phy_sel=1, USB_OTG is connected with internal PHY + RTCCNTL.usb_conf.sw_usb_phy_sel = 1; } static inline void usb_ll_ext_phy_enable(void) { USB_WRAP.otg_conf.pad_enable = 1; + // USB_OTG use external PHY USB_WRAP.otg_conf.phy_sel = 1; + // phy_sel is controlled by the following register value + RTCCNTL.usb_conf.sw_hw_usb_phy_sel = 1; + // phy_sel=sw_usb_phy_sel=0, USB_OTG is connected with external PHY through GPIO Matrix + RTCCNTL.usb_conf.sw_usb_phy_sel = 0; } static inline void usb_ll_int_phy_pullup_conf(bool dp_pu, bool dp_pd, bool dm_pu, bool dm_pd) diff --git a/components/soc/esp32s2/include/soc/soc_caps.h b/components/soc/esp32s2/include/soc/soc_caps.h index 63326b098a..13ef55669e 100644 --- a/components/soc/esp32s2/include/soc/soc_caps.h +++ b/components/soc/esp32s2/include/soc/soc_caps.h @@ -44,7 +44,7 @@ #define SOC_DEDICATED_GPIO_SUPPORTED 1 #define SOC_SUPPORTS_SECURE_DL_MODE 1 #define SOC_RISCV_COPROC_SUPPORTED 1 -#define SOC_USB_SUPPORTED 1 +#define SOC_USB_OTG_SUPPORTED 1 #define SOC_PCNT_SUPPORTED 1 #define SOC_ULP_SUPPORTED 1 #define SOC_RTC_SLOW_MEM_SUPPORTED 1 diff --git a/components/soc/esp32s3/include/soc/soc_caps.h b/components/soc/esp32s3/include/soc/soc_caps.h index a97f63c52a..1242ad4f64 100644 --- a/components/soc/esp32s3/include/soc/soc_caps.h +++ b/components/soc/esp32s3/include/soc/soc_caps.h @@ -15,6 +15,7 @@ #define SOC_CPU_CORES_NUM 2 #define SOC_CACHE_SUPPORT_WRAP 1 #define SOC_ULP_SUPPORTED 1 +#define SOC_USB_OTG_SUPPORTED 1 #define SOC_RTC_SLOW_MEM_SUPPORTED 1 #define SOC_CCOMP_TIMER_SUPPORTED 1 #define SOC_DIG_SIGN_SUPPORTED 0 diff --git a/components/soc/esp32s3/ld/esp32s3.peripherals.ld b/components/soc/esp32s3/ld/esp32s3.peripherals.ld index 6d86e13bfd..5b15a44618 100644 --- a/components/soc/esp32s3/ld/esp32s3.peripherals.ld +++ b/components/soc/esp32s3/ld/esp32s3.peripherals.ld @@ -37,5 +37,6 @@ PROVIDE ( DMA = 0x6003F000 ); PROVIDE ( APB_SARADC = 0x60040000 ); PROVIDE ( LCD_CAM = 0x60041000 ); PROVIDE ( USB_SERIAL_JTAG = 0x60038000 ); +PROVIDE ( USB0 = 0x60080000 ); PROVIDE ( USBH = 0x60080000 ); PROVIDE ( USB_WRAP = 0x60039000 ); 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/docs/_static/usb-board-connection.png b/docs/_static/usb-board-connection.png index cdb81eccf3..76bed54cf8 100644 Binary files a/docs/_static/usb-board-connection.png and b/docs/_static/usb-board-connection.png differ diff --git a/docs/conf_common.py b/docs/conf_common.py index 322b3198f2..390b106f95 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -164,7 +164,7 @@ LEGACY_DOCS = ['api-guides/build-system-legacy.rst', 'api-guides/unit-tests-legacy.rst', 'get-started-legacy/**'] -USB_DOCS = ['api-reference/peripherals/usb.rst', +USB_DOCS = ['api-reference/peripherals/usb_device.rst', 'api-guides/usb-otg-console.rst', 'api-guides/dfu.rst'] @@ -212,7 +212,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS, 'SOC_SDMMC_HOST_SUPPORTED':SDMMC_DOCS, 'SOC_SDIO_SLAVE_SUPPORTED':SDIO_SLAVE_DOCS, 'SOC_MCPWM_SUPPORTED':MCPWM_DOCS, - 'SOC_USB_SUPPORTED':USB_DOCS, + 'SOC_USB_OTG_SUPPORTED':USB_DOCS, 'SOC_USB_SERIAL_JTAG_SUPPORTED':USB_SERIAL_JTAG_DOCS, 'SOC_DEDICATED_GPIO_SUPPORTED':DEDIC_GPIO_DOCS, 'SOC_SPIRAM_SUPPORTED':SPIRAM_DOCS, diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index b2b750bfbb..22ce505dbd 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -12,7 +12,7 @@ API Guides Build System :esp32: Build System (Legacy GNU Make) Deep Sleep Wake Stubs - :SOC_USB_SUPPORTED: Device Firmware Upgrade through USB + :SOC_USB_OTG_SUPPORTED: Device Firmware Upgrade through USB Error Handling :SOC_BT_SUPPORTED: ESP-BLE-MESH ESP-WIFI-MESH @@ -41,6 +41,6 @@ API Guides Unit Testing (Target) Unit Testing (Linux Host) :esp32: Unit Testing (Legacy GNU Make) - :SOC_USB_SUPPORTED: USB OTG Console + :SOC_USB_OTG_SUPPORTED: USB OTG Console :SOC_USB_SERIAL_JTAG_SUPPORTED: USB Serial/JTAG Controller Console WiFi Driver diff --git a/docs/en/api-guides/performance/speed.rst b/docs/en/api-guides/performance/speed.rst index 87693a9f4e..b97132d11c 100644 --- a/docs/en/api-guides/performance/speed.rst +++ b/docs/en/api-guides/performance/speed.rst @@ -91,8 +91,8 @@ Although standard output is buffered, it's possible for an application to be lim .. list:: - Reduce the volume of log output by lowering the app :ref:`CONFIG_LOG_DEFAULT_LEVEL` (the equivalent bootloader setting is :ref:`CONFIG_BOOTLOADER_LOG_LEVEL`). This also reduces the binary size, and saves some CPU time spent on string formatting. - :not SOC_USB_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE` - :SOC_USB_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`. (Unless using internal USB-CDC for serial console, in which case the serial throughput doesn't depend on the configured baud rate.) + :not SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE` + :SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`. (Unless using internal USB-CDC for serial console, in which case the serial throughput doesn't depend on the configured baud rate.) Not Recommended ^^^^^^^^^^^^^^^ diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index 889d273945..d52fbd8e7f 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -33,6 +33,6 @@ Peripherals API :esp32s2: Touch Element TWAI UART - :SOC_USB_SUPPORTED: USB + :SOC_USB_OTG_SUPPORTED: USB Device Code examples for this API section are provided in the :example:`peripherals` directory of ESP-IDF examples. \ No newline at end of file diff --git a/docs/en/api-reference/peripherals/usb.rst b/docs/en/api-reference/peripherals/usb_device.rst similarity index 94% rename from docs/en/api-reference/peripherals/usb.rst rename to docs/en/api-reference/peripherals/usb_device.rst index 72bda70c93..6e3d1c1c91 100644 --- a/docs/en/api-reference/peripherals/usb.rst +++ b/docs/en/api-reference/peripherals/usb_device.rst @@ -1,6 +1,9 @@ -USB Driver -========== +USB Device Driver +================= + +{IDF_TARGET_USB_DP_GPIO_NUM:default="20"} +{IDF_TARGET_USB_DM_GPIO_NUM:default="19"} Overview -------- @@ -21,12 +24,14 @@ Hardware USB Connection - Any board with the {IDF_TARGET_NAME} chip with USB connectors or with exposed USB's D+ and D- (DATA+/DATA-) pins. -If the board has no USB connector but has the pins, connect pins directly to the host (e.g. with do-it-yourself cable from any USB connection cable). For example, connect GPIO19/20 to D-/D+ respectively for an ESP32-S2 board: +If the board has no USB connector but has the pins, connect pins directly to the host (e.g. with do-it-yourself cable from any USB connection cable). + +On {IDF_TARGET_NAME}, connect GPIO {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} to D+/D- respectively: .. figure:: ../../../_static/usb-board-connection.png :align: center - :alt: Connection of a board to a host ESP32-S2 + :alt: Connection of a board to a host ESP chip :figclass: align-center Driver Structure diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index 189611c0a0..df312052fd 100644 --- a/docs/en/api-reference/system/freertos_additions.rst +++ b/docs/en/api-reference/system/freertos_additions.rst @@ -25,8 +25,8 @@ Ring Buffers The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items. Ring buffers are a more memory efficient alternative to FreeRTOS queues in situations where the size of items is variable. The capacity of a ring buffer is not measured by the number of items -it can store, but rather by the amount of memory used for storing items. The ring buffer provides API -to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. +it can store, but rather by the amount of memory used for storing items. The ring buffer provides API +to send an item, or to allocate space for an item in the ring buffer to be filled manually by the user. For efficiency reasons, **items are always retrieved from the ring buffer by reference**. As a result, all retrieved items *must also be returned* to the ring buffer by using :cpp:func:`vRingbufferReturnItem` or :cpp:func:`vRingbufferReturnItemFromISR`, in order for them to be removed from the ring buffer completely. @@ -531,6 +531,6 @@ Hooks API Reference Component Specific Properties ----------------------------- -Besides standart component variables that could be gotten with basic cmake build properties FreeRTOS component also provides an arguments (only one so far) for simpler integration with other modules: +Besides standard component variables that could be gotten with basic cmake build properties FreeRTOS component also provides an arguments (only one so far) for simpler integration with other modules: - `ORIG_INCLUDE_PATH` - contains an absolute path to freertos root include folder. Thus instead of `#include "freertos/FreeRTOS.h"` you can refer to headers directly: `#include "FreeRTOS.h"`. diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt index 33a5583ea1..e5725f82e2 100644 --- a/docs/page_redirects.txt +++ b/docs/page_redirects.txt @@ -16,6 +16,7 @@ api-reference/ethernet/esp_eth api-reference/network/esp_eth api-reference/mesh/index api-reference/network/index api-reference/mesh/esp_mesh api-reference/network/esp_mesh api-reference/peripherals/can api-reference/peripherals/twai +api-reference/peripherals/usb api-reference/peripherals/usb_device api-reference/wifi/index api-reference/network/index api-reference/wifi/esp_now api-reference/network/esp_now api-reference/wifi/esp_smartconfig api-reference/network/esp_smartconfig diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index 842f38da88..e23b69ae91 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -12,7 +12,7 @@ API 指南 构建系统 :esp32: 构建系统 (传统 GNU Make) 深度睡眠唤醒存根 - :esp32s2: 通过 USB 升级设备固件 + :SOC_USB_OTG_SUPPORTED: 通过 USB 升级设备固件 错误处理 :SOC_BT_SUPPORTED: ESP-BLE-MESH ESP-WIFI-MESH @@ -41,6 +41,6 @@ API 指南 单元测试 (Target) 单元测试 (Linux Host) :esp32: 单元测试 (传统 GNU Make) - :SOC_USB_SUPPORTED: USB 控制台 + :SOC_USB_OTG_SUPPORTED: USB 控制台 :SOC_USB_SERIAL_JTAG_SUPPORTED: USB Serial/JTAG Controller Console Wi-Fi 驱动 diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 8aca2ff658..373b041ed5 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -33,6 +33,6 @@ :esp32s2: Touch Element TWAI UART - :SOC_USB_SUPPORTED: USB + :SOC_USB_OTG_SUPPORTED: USB Device 本部分的 API 示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals` 目录下。 \ No newline at end of file diff --git a/docs/zh_CN/api-reference/peripherals/usb.rst b/docs/zh_CN/api-reference/peripherals/usb.rst deleted file mode 100644 index 6fc57107c6..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/peripherals/usb.rst diff --git a/docs/zh_CN/api-reference/peripherals/usb_device.rst b/docs/zh_CN/api-reference/peripherals/usb_device.rst new file mode 100644 index 0000000000..eeb934409f --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/usb_device.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/peripherals/usb_device.rst 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