fix(usb_device): esp_tinyusb 3.x with a single TinyUSB copy (fixes manager-on CI builds)

.gitmodules

@@ -43,9 +43,6 @@
 [submodule "components/cdr/detail/cdr"]
 	path = components/cdr/detail/cdr
 	url = https://github.com/finger563/cdr.git
-[submodule "external/tinyusb"]
-	path = external/tinyusb
-	url = https://github.com/espressif/tinyusb.git
 [submodule "external/esp-usb"]
 	path = external/esp-usb
 	url = https://github.com/espressif/esp-usb.git

components/bldc_haptics/example/CMakeLists.txt

@@ -55,13 +55,13 @@ set(EXTRA_COMPONENT_DIRS
 
 # With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
 # build does not need the as-yet unpublished espp/* components in the registry),
-# esp_tinyusb/tinyusb are not fetched; add the vendored submodule copies under
-# external/ to the search path. esp_tinyusb's CMakeLists adds `tinyusb` to its
-# REQUIRES when the manager is off, so both directories must be discoverable.
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/bldc_haptics/example/main/bldc_haptics_example.cpp

@@ -12,8 +12,8 @@
 
 #include "esp_system.h"
 #include "esp_timer.h"
-#include "tusb_cdc_acm.h"
-#include "tusb_console.h"
+#include "tinyusb_cdc_acm.h"
+#include "tinyusb_console.h"
 
 #include "format.hpp"
 
@@ -347,7 +347,7 @@ extern "C" void app_main(void) {
   usb_cfg.log_level = espp::Logger::Verbosity::INFO;
   // CDC alongside the vendor interface: a plain serial port any terminal can
   // attach to (e.g. `screen /dev/tty.usbmodem*`). Once USB is up it becomes
-  // the live SYSTEM console (esp_tusb_init_console below routes stdout/stderr
+  // the live SYSTEM console (tinyusb_console_init below routes stdout/stderr
   // - all espp/fmt and esp_log output - to it) and re-logs the last-crash
   // report on every connect. Panic backtraces still cannot appear live
   // (TinyUSB dies with the panic); the flash core dump + next-boot report
@@ -672,7 +672,7 @@ extern "C" void app_main(void) {
     // backtraces still cannot appear live (TinyUSB dies with the panic) -
     // those are captured by the flash core dump and summarized on the next
     // boot (see crash_report above / GET_CRASH).
-    if (esp_tusb_init_console(TINYUSB_CDC_ACM_0) != ESP_OK)
+    if (tinyusb_console_init(TINYUSB_CDC_ACM_0) != ESP_OK)
       logger.warn("Could not route the console to USB CDC");
   }
 

components/bldc_haptics/example/sdkconfig.defaults

@@ -49,7 +49,7 @@ CONFIG_TINYUSB_VENDOR_RX_BUFSIZE=4200
 CONFIG_TINYUSB_VENDOR_TX_BUFSIZE=4200
 
 # CDC is instantiated and used: the example exposes a CDC-ACM debug serial
-# port and routes the system console to it (esp_tusb_init_console), so keep
+# port and routes the system console to it (tinyusb_console_init), so keep
 # the CDC class driver enabled. HID is compile-only: the usb_device
 # component's sources reference the TinyUSB HID class driver APIs, which
 # esp_tinyusb gates behind CONFIG_TINYUSB_HID_COUNT -- keep it > 0 so the

components/canopen/can_bridge_example/CMakeLists.txt

@@ -35,14 +35,15 @@ set(EXTRA_COMPONENT_DIRS
   "../../../components/usb_device"
 )
 
-# With the component manager disabled, esp_tinyusb/tinyusb are not fetched from
-# the registry; add the vendored submodule copies to the component search path.
-# esp_tinyusb's own CMakeLists adds `tinyusb` to its REQUIRES when the manager is
-# off, so both component directories must be discoverable here.
+# With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
+# build does not need the as-yet unpublished espp/* components in the registry),
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/coredump/example/CMakeLists.txt

@@ -33,13 +33,13 @@ set(EXTRA_COMPONENT_DIRS
 
 # With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
 # build does not need the as-yet unpublished espp/* components in the registry),
-# esp_tinyusb/tinyusb are not fetched; add the vendored submodule copies under
-# external/ to the search path. esp_tinyusb's CMakeLists adds `tinyusb` to its
-# REQUIRES when the manager is off, so both directories must be discoverable.
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/coredump/example/sdkconfig.defaults

@@ -25,7 +25,7 @@ CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG=y
 # works.
 CONFIG_TINYUSB_VENDOR_COUNT=1
 
-# The CDC function carries the system console (esp_tusb_init_console) AND the
+# The CDC function carries the system console (route_console_to_cdc / tinyusb_console_init) AND the
 # core-dump protocol frames (the web console's Web Serial transport); the HID
 # count just keeps the usb_device component's HID references compiling (no HID
 # interface is instantiated here).

components/desktop/example/CMakeLists.txt

@@ -75,7 +75,6 @@ if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../components/littlefs"
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/mcp266/webapp_example/CMakeLists.txt

@@ -37,14 +37,15 @@ set(EXTRA_COMPONENT_DIRS
   "../../../components/usb_device"
 )
 
-# With the component manager disabled, esp_tinyusb/tinyusb are not fetched from
-# the registry; add the vendored submodule copies to the component search path.
-# esp_tinyusb's own CMakeLists adds `tinyusb` to its REQUIRES when the manager is
-# off, so both component directories must be discoverable here.
+# With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
+# build does not need the as-yet unpublished espp/* components in the registry),
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/ota/example/CMakeLists.txt

@@ -32,13 +32,13 @@ set(EXTRA_COMPONENT_DIRS
 
 # With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
 # build does not need the as-yet unpublished espp/* components in the registry),
-# esp_tinyusb/tinyusb are not fetched; add the vendored submodule copies under
-# external/ to the search path. esp_tinyusb's CMakeLists adds `tinyusb` to its
-# REQUIRES when the manager is off, so both directories must be discoverable.
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/switch_pro/example/CMakeLists.txt

@@ -18,14 +18,13 @@ set(EXTRA_COMPONENT_DIRS
 
 # With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
 # build does not need the as-yet unpublished espp/* components in the registry),
-# esp_tinyusb/tinyusb are not fetched from the registry; add the vendored
-# submodule copies under external/ to the search path. esp_tinyusb's CMakeLists
-# adds `tinyusb` to its REQUIRES when the manager is off, so both directories
-# must be discoverable.
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/system/example/CMakeLists.txt

@@ -34,7 +34,6 @@ set(EXTRA_COMPONENT_DIRS
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/telemetry/example/CMakeLists.txt

@@ -35,13 +35,13 @@ set(EXTRA_COMPONENT_DIRS
 
 # With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
 # build does not need the as-yet unpublished espp/* components in the registry),
-# esp_tinyusb/tinyusb are not fetched; add the vendored submodule copies under
-# external/ to the search path. esp_tinyusb's CMakeLists adds `tinyusb` to its
-# REQUIRES when the manager is off, so both directories must be discoverable.
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/usb_device/README.md

@@ -7,6 +7,13 @@ component that assembles a **native USB device** from a *set of selectable
 functions* on the ESP32-S3 / -S2 / -P4 USB-OTG peripheral, with a **configurable
 VID/PID** and manufacturer / product / serial strings.
 
+It requires `espressif/esp_tinyusb` 3.0 or newer (ESP-IDF 5.3 or newer), which
+ships TinyUSB as its own submodule: projects must not add a separate `tinyusb`
+dependency, since a second copy of the stack cannot find `tusb_config.h` and the
+build fails. With the component manager off, the vendored copy under
+`external/esp-usb/device/esp_tinyusb` (initialised recursively) is the one to put
+on `EXTRA_COMPONENT_DIRS`; the examples show the pattern.
+
 Today it can enable, in any combination (subject to the endpoint budget):
 
 - A **CDC-ACM** function (virtual serial port).

components/usb_device/example/CMakeLists.txt

@@ -35,7 +35,6 @@ set(EXTRA_COMPONENT_DIRS
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/usb_device/idf_component.yml

@@ -28,17 +28,14 @@ tags:
   - SD-Card
 dependencies:
   idf:
-    version: '>=5.0'
+    version: '>=5.3'
   espp/base_component: '>=1.0'
-  # >= 2.0.1: MSC storage-operation multitask protection, and delete_storage()
-  # refusing to free a storage with host writes still queued (MSC teardown
-  # relies on both).
-  espressif/esp_tinyusb: '>=2.0.1'
-  # The X-Input class driver uses the 5-argument usbd_edpt_xfer(..., is_isr) API
-  # (and the usbd_class_driver_t `xfer_isr` member). TinyUSB 0.21 provides that
-  # 5-argument form; earlier releases (e.g. 0.19) still have the 4-argument
-  # usbd_edpt_xfer, which fails to compile here. esp_tinyusb only requires tinyusb
-  # >= 0.17, so pin the tested 0.21 floor here.
-  tinyusb:
-    version: '>=0.21.0'
-    public: true
+  # >= 3.0.0: esp_tinyusb ships TinyUSB (0.21.0~2 in 3.0.0) as its own
+  # submodule and no longer depends on the registry `tinyusb` component. Do not
+  # add a `tinyusb` dependency here: with esp_tinyusb 3.x it pulls a second copy
+  # of the stack that cannot find tusb_config.h and the build fails. 3.0.0 also
+  # carries everything this component needs from 2.x (MSC multitask protection
+  # and delete_storage() refusing to free a storage with host writes queued) and
+  # the TinyUSB 0.21 5-argument usbd_edpt_xfer(..., is_isr) the X-Input class
+  # driver uses. esp_tinyusb 3.x requires ESP-IDF >= 5.3.
+  espressif/esp_tinyusb: '>=3.0.0'

components/usb_device/msc_example/CMakeLists.txt

@@ -30,14 +30,13 @@ set(EXTRA_COMPONENT_DIRS
 
 # With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
 # build does not need the as-yet unpublished espp/* components in the registry),
-# esp_tinyusb/tinyusb are not fetched from the registry; add the vendored
-# submodule copies under external/ to the search path. esp_tinyusb's CMakeLists
-# adds `tinyusb` to its REQUIRES when the manager is off, so both directories
-# must be discoverable.
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/usb_device/msc_example/README.md

@@ -30,11 +30,11 @@ USB port's PHY with USB-OTG, which the mass storage interface takes over.
 The build works with the IDF component manager on (esp_tinyusb comes from the
 registry) or off, which is how CI builds it and the way to go while a local espp
 component the example uses is not published yet. With the manager off,
-esp_tinyusb and TinyUSB come from the vendored submodules, so initialize them
-first:
+esp_tinyusb (which bundles TinyUSB as a nested submodule) comes from the
+vendored submodule, so initialize it first:
 
 ```sh
-git submodule update --init external/esp-usb external/tinyusb components/lvgl components/format/detail/fmt
+git submodule update --init --recursive external/esp-usb components/lvgl components/format/detail/fmt
 IDF_COMPONENT_MANAGER=0 idf.py -p <PORT> flash monitor
 ```
 

components/usb_device/xinput_example/CMakeLists.txt

@@ -14,14 +14,13 @@ set(EXTRA_COMPONENT_DIRS
 
 # With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
 # build does not need the as-yet unpublished espp/* components in the registry),
-# esp_tinyusb/tinyusb are not fetched from the registry; add the vendored
-# submodule copies under external/ to the search path. esp_tinyusb's CMakeLists
-# adds `tinyusb` to its REQUIRES when the manager is off, so both directories
-# must be discoverable.
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/vl53l/vl53l5cx_webapp_example/CMakeLists.txt

@@ -37,14 +37,15 @@ set(EXTRA_COMPONENT_DIRS
   "../../../components/vl53l"
 )
 
-# With the component manager disabled, esp_tinyusb/tinyusb are not fetched from
-# the registry; add the vendored submodule copies to the component search path.
-# esp_tinyusb's own CMakeLists adds `tinyusb` to its REQUIRES when the manager is
-# off, so both component directories must be discoverable here.
+# With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
+# build does not need the as-yet unpublished espp/* components in the registry),
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()
 

components/wdi/usb_example/CMakeLists.txt

@@ -18,14 +18,13 @@ set(EXTRA_COMPONENT_DIRS
 
 # With the component manager disabled (IDF_COMPONENT_MANAGER=0, e.g. in CI so the
 # build does not need the as-yet unpublished espp/* components in the registry),
-# esp_tinyusb/tinyusb are not fetched from the registry; add the vendored
-# submodule copies under external/ to the search path. esp_tinyusb's CMakeLists
-# adds `tinyusb` to its REQUIRES when the manager is off, so both directories
-# must be discoverable.
+# esp_tinyusb is not fetched from the registry; add the vendored submodule copy
+# under external/ to the search path. esp_tinyusb >= 3.0 ships TinyUSB as its own
+# nested submodule (external/esp-usb/device/esp_tinyusb/tinyusb), so that one
+# directory is all that is needed; a second TinyUSB copy must NOT be on the path.
 if(DEFINED ENV{IDF_COMPONENT_MANAGER} AND "$ENV{IDF_COMPONENT_MANAGER}" STREQUAL "0")
   list(APPEND EXTRA_COMPONENT_DIRS
     "../../../external/esp-usb/device/esp_tinyusb"
-    "../../../external/tinyusb"
   )
 endif()