Merge branch 'feature/usb_device/pytests' into 'master'

tinyusb: Add TinyUSB example tests

See merge request espressif/esp-idf!19194

.gitlab/ci/dependencies/dependencies.yml

@@ -167,6 +167,7 @@ build:integration_test:
       - wifi      # example_test_002, example_test*wifi*
       - ethernet  # example_test*ethernet*
       - sdio      # UT_044, UT_045
+      - usb       # USB Device & Host tests
   patterns:
     - "{0}-{1}-{2}"
     - "{0}-{2}"

.gitlab/ci/rules.yml

@@ -221,6 +221,15 @@
   - "components/driver/**/*"
   - "components/sdmmc/**/*"
 
+# for jobs: example_test_pytest_esp32s3_usb_device and test_app_test_pytest_esp32s2_usb_host:
+.patterns-example_test-usb: &patterns-example_test-usb
+  - "components/hal/usb*.c"
+  - "components/hal/esp32s*/include/hal/usb*.h"
+  - "components/tinyusb/**/**/*"
+  - "components/usb/**/*"
+  - "examples/peripherals/usb/host/**/**/**/*"
+  - "examples/peripherals/usb/device/**/**/*"
+
 
 ##############
 # if anchors #
@@ -765,6 +774,8 @@
       changes: *patterns-example_test-bt
     - <<: *if-dev-push
       changes: *patterns-example_test-ethernet
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
     - <<: *if-dev-push
       changes: *patterns-example_test-wifi
 
@@ -791,6 +802,8 @@
       changes: *patterns-example_test-bt
     - <<: *if-dev-push
       changes: *patterns-example_test-ethernet
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
     - <<: *if-dev-push
       changes: *patterns-example_test-wifi
 
@@ -811,6 +824,8 @@
       changes: *patterns-example_test-bt
     - <<: *if-dev-push
       changes: *patterns-example_test-ethernet
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
     - <<: *if-dev-push
       changes: *patterns-example_test-wifi
 
@@ -836,6 +851,8 @@
       changes: *patterns-example_test-bt
     - <<: *if-dev-push
       changes: *patterns-example_test-ethernet
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
     - <<: *if-dev-push
       changes: *patterns-example_test-wifi
 
@@ -860,6 +877,8 @@
       changes: *patterns-example_test-bt
     - <<: *if-dev-push
       changes: *patterns-example_test-ethernet
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
     - <<: *if-dev-push
       changes: *patterns-example_test-wifi
 
@@ -884,6 +903,8 @@
       changes: *patterns-example_test-bt
     - <<: *if-dev-push
       changes: *patterns-example_test-ethernet
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
     - <<: *if-dev-push
       changes: *patterns-example_test-wifi
 
@@ -908,6 +929,8 @@
       changes: *patterns-example_test-bt
     - <<: *if-dev-push
       changes: *patterns-example_test-ethernet
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
     - <<: *if-dev-push
       changes: *patterns-example_test-wifi
 
@@ -993,6 +1016,8 @@
       changes: *patterns-example_test-bt
     - <<: *if-dev-push
       changes: *patterns-example_test-ethernet
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
     - <<: *if-dev-push
       changes: *patterns-example_test-wifi
     - <<: *if-dev-push
@@ -1225,6 +1250,17 @@
     - <<: *if-label-component_ut_esp32
     - <<: *if-label-target_test
 
+.rules:test:component_ut-esp32-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-component_ut
+    - <<: *if-label-component_ut_esp32
+    - <<: *if-label-target_test
+
 .rules:test:component_ut-esp32-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1279,6 +1315,17 @@
     - <<: *if-label-component_ut_esp32c2
     - <<: *if-label-target_test
 
+.rules:test:component_ut-esp32c2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-component_ut
+    - <<: *if-label-component_ut_esp32c2
+    - <<: *if-label-target_test
+
 .rules:test:component_ut-esp32c2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1338,6 +1385,17 @@
     - <<: *if-label-component_ut_esp32c3
     - <<: *if-label-target_test
 
+.rules:test:component_ut-esp32c3-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-component_ut
+    - <<: *if-label-component_ut_esp32c3
+    - <<: *if-label-target_test
+
 .rules:test:component_ut-esp32c3-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1397,6 +1455,17 @@
     - <<: *if-label-component_ut_esp32h2
     - <<: *if-label-target_test
 
+.rules:test:component_ut-esp32h2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-component_ut
+    - <<: *if-label-component_ut_esp32h2
+    - <<: *if-label-target_test
+
 .rules:test:component_ut-esp32h2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1456,6 +1525,17 @@
     - <<: *if-label-component_ut_esp32s2
     - <<: *if-label-target_test
 
+.rules:test:component_ut-esp32s2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-component_ut
+    - <<: *if-label-component_ut_esp32s2
+    - <<: *if-label-target_test
+
 .rules:test:component_ut-esp32s2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1510,6 +1590,17 @@
     - <<: *if-label-component_ut_esp32s3
     - <<: *if-label-target_test
 
+.rules:test:component_ut-esp32s3-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-component_ut
+    - <<: *if-label-component_ut_esp32s3
+    - <<: *if-label-target_test
+
 .rules:test:component_ut-esp32s3-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1567,6 +1658,17 @@
     - <<: *if-label-custom_test_esp32
     - <<: *if-label-target_test
 
+.rules:test:custom_test-esp32-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-custom_test
+    - <<: *if-label-custom_test_esp32
+    - <<: *if-label-target_test
+
 .rules:test:custom_test-esp32-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1620,6 +1722,17 @@
     - <<: *if-label-custom_test_esp32c2
     - <<: *if-label-target_test
 
+.rules:test:custom_test-esp32c2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-custom_test
+    - <<: *if-label-custom_test_esp32c2
+    - <<: *if-label-target_test
+
 .rules:test:custom_test-esp32c2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1677,6 +1790,17 @@
     - <<: *if-label-custom_test_esp32c3
     - <<: *if-label-target_test
 
+.rules:test:custom_test-esp32c3-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-custom_test
+    - <<: *if-label-custom_test_esp32c3
+    - <<: *if-label-target_test
+
 .rules:test:custom_test-esp32c3-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1734,6 +1858,17 @@
     - <<: *if-label-custom_test_esp32h2
     - <<: *if-label-target_test
 
+.rules:test:custom_test-esp32h2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-custom_test
+    - <<: *if-label-custom_test_esp32h2
+    - <<: *if-label-target_test
+
 .rules:test:custom_test-esp32h2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1791,6 +1926,17 @@
     - <<: *if-label-custom_test_esp32s2
     - <<: *if-label-target_test
 
+.rules:test:custom_test-esp32s2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-custom_test
+    - <<: *if-label-custom_test_esp32s2
+    - <<: *if-label-target_test
+
 .rules:test:custom_test-esp32s2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1844,6 +1990,17 @@
     - <<: *if-label-custom_test_esp32s3
     - <<: *if-label-target_test
 
+.rules:test:custom_test-esp32s3-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-custom_test
+    - <<: *if-label-custom_test_esp32s3
+    - <<: *if-label-target_test
+
 .rules:test:custom_test-esp32s3-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1916,6 +2073,19 @@
     - <<: *if-label-example_test_esp32
     - <<: *if-label-target_test
 
+.rules:test:example_test-esp32-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-example_test
+    - <<: *if-label-example_test_esp32
+    - <<: *if-label-target_test
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
+
 .rules:test:example_test-esp32-wifi:
   rules:
     - <<: *if-revert-branch
@@ -1975,6 +2145,19 @@
     - <<: *if-label-example_test_esp32c2
     - <<: *if-label-target_test
 
+.rules:test:example_test-esp32c2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-example_test
+    - <<: *if-label-example_test_esp32c2
+    - <<: *if-label-target_test
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
+
 .rules:test:example_test-esp32c2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2049,6 +2232,19 @@
     - <<: *if-label-example_test_esp32c3
     - <<: *if-label-target_test
 
+.rules:test:example_test-esp32c3-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-example_test
+    - <<: *if-label-example_test_esp32c3
+    - <<: *if-label-target_test
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
+
 .rules:test:example_test-esp32c3-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2114,6 +2310,19 @@
     - <<: *if-label-example_test_esp32h2
     - <<: *if-label-target_test
 
+.rules:test:example_test-esp32h2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-example_test
+    - <<: *if-label-example_test_esp32h2
+    - <<: *if-label-target_test
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
+
 .rules:test:example_test-esp32h2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2179,6 +2388,19 @@
     - <<: *if-label-example_test_esp32s2
     - <<: *if-label-target_test
 
+.rules:test:example_test-esp32s2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-example_test
+    - <<: *if-label-example_test_esp32s2
+    - <<: *if-label-target_test
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
+
 .rules:test:example_test-esp32s2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2238,6 +2460,19 @@
     - <<: *if-label-example_test_esp32s3
     - <<: *if-label-target_test
 
+.rules:test:example_test-esp32s3-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-example_test
+    - <<: *if-label-example_test_esp32s3
+    - <<: *if-label-target_test
+    - <<: *if-dev-push
+      changes: *patterns-example_test-usb
+
 .rules:test:example_test-esp32s3-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2333,6 +2568,17 @@
     - <<: *if-dev-push
       changes: *patterns-unit_test-sdio
 
+.rules:test:unit_test-esp32-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-target_test
+    - <<: *if-label-unit_test
+    - <<: *if-label-unit_test_esp32
+
 .rules:test:unit_test-esp32-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2388,6 +2634,17 @@
     - <<: *if-dev-push
       changes: *patterns-unit_test-sdio
 
+.rules:test:unit_test-esp32c2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-target_test
+    - <<: *if-label-unit_test
+    - <<: *if-label-unit_test_esp32c2
+
 .rules:test:unit_test-esp32c2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2447,6 +2704,17 @@
     - <<: *if-dev-push
       changes: *patterns-unit_test-sdio
 
+.rules:test:unit_test-esp32c3-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-target_test
+    - <<: *if-label-unit_test
+    - <<: *if-label-unit_test_esp32c3
+
 .rules:test:unit_test-esp32c3-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2506,6 +2774,17 @@
     - <<: *if-dev-push
       changes: *patterns-unit_test-sdio
 
+.rules:test:unit_test-esp32h2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-target_test
+    - <<: *if-label-unit_test
+    - <<: *if-label-unit_test_esp32h2
+
 .rules:test:unit_test-esp32h2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2565,6 +2844,17 @@
     - <<: *if-dev-push
       changes: *patterns-unit_test-sdio
 
+.rules:test:unit_test-esp32s2-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-target_test
+    - <<: *if-label-unit_test
+    - <<: *if-label-unit_test_esp32s2
+
 .rules:test:unit_test-esp32s2-wifi:
   rules:
     - <<: *if-revert-branch
@@ -2620,6 +2910,17 @@
     - <<: *if-dev-push
       changes: *patterns-unit_test-sdio
 
+.rules:test:unit_test-esp32s3-usb:
+  rules:
+    - <<: *if-revert-branch
+      when: never
+    - <<: *if-protected
+    - <<: *if-label-build-only
+      when: never
+    - <<: *if-label-target_test
+    - <<: *if-label-unit_test
+    - <<: *if-label-unit_test_esp32s3
+
 .rules:test:unit_test-esp32s3-wifi:
   rules:
     - <<: *if-revert-branch

.gitlab/ci/target-test.yml

@@ -208,6 +208,14 @@ example_test_pytest_esp32c3_flash_encryption:
     - build_pytest_examples_esp32c3
   tags: [ esp32c3, flash_encryption ]
 
+example_test_pytest_esp32s2_usb_device:
+  extends:
+    - .pytest_examples_dir_template
+    - .rules:test:example_test-esp32s2-usb
+  needs:
+    - build_pytest_examples_esp32s2
+  tags: [ esp32s2, usb_device ]
+
 .pytest_components_dir_template:
   extends: .pytest_template
   variables:

docs/en/api-reference/peripherals/usb_device.rst

@@ -11,7 +11,7 @@ USB Device Driver
 Overview
 --------
 
-The driver allows users to use {IDF_TARGET_NAME} chips to develop USB devices on a top of the TinyUSB stack. TinyUSB is integrated with ESP-IDF to provide USB features of the framework. Using this driver the chip works as a composite device supporting several USB devices simultaneously. Currently, only the Communications Device Class (CDC) type of the device with the Abstract Control Model (ACM) subclass and the Musical Instrument Digital Interface (MIDI) are supported.
+The driver allows you to use {IDF_TARGET_NAME} chips to develop USB devices on a top of TinyUSB stack. TinyUSB is integrated with ESP-IDF to provide USB features of the framework. Using this driver the chip works as simple or composite device supporting several USB devices simultaneously.
 
 Our USB-OTG implementation is limited to {IDF_TARGET_USB_EP_NUM} number of USB endpoints ({IDF_TARGET_USB_EP_NUM_INOUT} IN/OUT endpoints and {IDF_TARGET_USB_EP_NUM_IN} IN endpoint) - find more information in `technical reference manual <{IDF_TARGET_TRM_EN_URL}>`_.
 
@@ -20,8 +20,8 @@ Features
 
 - Configuration of device and string USB descriptors
 - USB Serial Device (CDC-ACM)
-- Input and output through USB Serial Device
-- USB MIDI Device
+- Input and output streams through USB Serial Device
+- Other USB classes (MIDI, MSC, HID...) support directly via TinyUSB
 
 
 Hardware USB Connection
@@ -67,9 +67,9 @@ Via Menuconfig options you can specify:
 Descriptors Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The driver's descriptors are provided by the :cpp:type:`tinyusb_config_t` structure's :cpp:member:`descriptor` and :cpp:member:`string_descriptor` members. Therefore, users should initialize :cpp:type:`tinyusb_config_t` to their desired descriptor before calling :cpp:func:`tinyusb_driver_install` to install driver.
+The driver's descriptors are provided by :cpp:type:`tinyusb_config_t` structure's :cpp:member:`device_descriptor`, :cpp:member:`configuration_descriptor` and :cpp:member:`string_descriptor` members. Therefore, you should initialize :cpp:type:`tinyusb_config_t` with your desired descriptors before calling :cpp:func:`tinyusb_driver_install` to install the driver.
 
-However, the driver also provides a default descriptor. The driver can be installed with the default descriptor by setting the :cpp:member:`descriptor` and :cpp:member:`string_descriptor` members of :cpp:type:`tinyusb_config_t` to `NULL` before calling :cpp:func:`tinyusb_driver_install`. The driver's default descriptor is specified using Menuconfig, where the following fields should be configured:
+However, the driver also provides default descriptors. You can install the driver with default device and string descriptors by setting the :cpp:member:`device_descriptor` and :cpp:member:`string_descriptor` members of :cpp:type:`tinyusb_config_t` to `NULL` before calling :cpp:func:`tinyusb_driver_install`. To lower your development effort we also provide default configuration descriptor for CDC and MSC class, as these classes rarely require custom configuration. The driver's default device descriptor is specified using Menuconfig, where the following fields should be configured:
 
 - PID
 - VID
@@ -79,31 +79,32 @@ However, the driver also provides a default descriptor. The driver can be instal
 - Name of CDC device if it is On
 - Serial number
 
-If you want to use own descriptors with extended modification, you can define them during the driver installation process
+If you want to use your own descriptors with extended modification, you can define them during the driver installation process.
 
 
 Install Driver
 --------------
 To initialize the driver, users should call :cpp:func:`tinyusb_driver_install`. The driver's configuration is specified in a :cpp:type:`tinyusb_config_t` structure that is passed as an argument to :cpp:func:`tinyusb_driver_install`.
 
- Note that the :cpp:type:`tinyusb_config_t` structure can be zero initialized (e.g. ``tinyusb_config_t tusb_cfg = { 0 }``) or partially (as shown below). For any member that is initialized to `0` or `NULL`, the driver will use its default configuration values for that member (see example below)
+ Note that the :cpp:type:`tinyusb_config_t` structure can be zero initialized (e.g. ``const tinyusb_config_t tusb_cfg = { 0 };``) or partially (as shown below). For any member that is initialized to `0` or `NULL`, the driver will use its default configuration values for that member (see example below)
 
 .. code-block:: c
 
-    tinyusb_config_t partial_init = {
-        .descriptor = NULL;         //Uses default descriptor specified in Menuconfig
-        .string_descriptor = NULL;  //Uses default string specified in Menuconfig
-        .external_phy = false;
-    }
+    const tinyusb_config_t partial_init = {
+        .device_descriptor = NULL,  // Use default device descriptor specified in Menuconfig
+        .string_descriptor = NULL,  // Use default string descriptors specified in Menuconfig
+        .external_phy = false,      // Use internal USB PHY
+        .configuration_descriptor = NULL, // Use default configuration descriptor according to settings in Menuconfig
+    };
 
 USB Serial Device (CDC-ACM)
 ---------------------------
 
-If the CDC option is enabled in Menuconfig, the USB Serial Device could be initialized with :cpp:func:`tusb_cdc_acm_init` according to the settings from :cpp:type:`tinyusb_config_cdcacm_t` (see example below).
+If the CDC option is enabled in Menuconfig, the USB Serial Device can be initialized with :cpp:func:`tusb_cdc_acm_init` according to the settings from :cpp:type:`tinyusb_config_cdcacm_t` (see example below).
 
 .. code-block:: c
 
-    tinyusb_config_cdcacm_t acm_cfg = {
+    const tinyusb_config_cdcacm_t acm_cfg = {
         .usb_dev = TINYUSB_USBDEV_0,
         .cdc_port = TINYUSB_CDC_ACM_0,
         .rx_unread_buf_sz = 64,
@@ -119,7 +120,7 @@ To specify callbacks you can either set the pointer to your :cpp:type:`tusb_cdca
 USB Serial Console
 ^^^^^^^^^^^^^^^^^^
 
-The driver allows to redirect all standard application strings (stdin/out/err) to the USB Serial Device and return them to UART using :cpp:func:`esp_tusb_init_console`/:cpp:func:`esp_tusb_deinit_console` functions.
+The driver allows to redirect all standard application streams (stdinm stdout, stderr) to the USB Serial Device and return them to UART using :cpp:func:`esp_tusb_init_console`/:cpp:func:`esp_tusb_deinit_console` functions.
 
 
 Application Examples
@@ -135,12 +136,12 @@ The table below describes the code examples available in the directory :example:
      - Description
    * - :example:`peripherals/usb/device/tusb_console`
      - How to set up {IDF_TARGET_NAME} chip to get log output via Serial Device connection
-   * - :example:`peripherals/usb/device/tusb_sample_descriptor`
-     - How to set up {IDF_TARGET_NAME} chip to work as a Generic USB Device with a user-defined descriptor
    * - :example:`peripherals/usb/device/tusb_serial_device`
      - How to set up {IDF_TARGET_NAME} chip to work as a USB Serial Device
    * - :example:`peripherals/usb/device/tusb_midi`
      - How to set up {IDF_TARGET_NAME} chip to work as a USB MIDI Device
+   * - :example:`peripherals/usb/device/tusb_hid`
+     - How to set up {IDF_TARGET_NAME} chip to work as a USB Human Interface Device
 
 
 API Reference

examples/peripherals/usb/device/.build-test-rules.yml

@@ -0,0 +1,9 @@
+# Documentation: .gitlab/ci/README.md#manifest-file-to-control-the-buildtest-apps
+
+examples/peripherals/usb/device:
+  enable:
+    - if: SOC_USB_OTG_SUPPORTED == 1
+  disable_test:
+    - if: IDF_TARGET == "esp32s3"
+      temporary: true
+      reason: lack of runners

examples/peripherals/usb/device/tusb_console/pytest_usb_device_console.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: CC0-1.0
+from time import sleep
+
+import pytest
+from pytest_embedded import Dut
+from serial import Serial
+from serial.tools.list_ports import comports
+
+
+@pytest.mark.esp32s2
+@pytest.mark.usb_device
+def test_usb_device_console_example(dut: Dut) -> None:
+    dut.expect_exact('USB initialization DONE')
+    dut.expect_exact('example: log -> UART')
+    dut.expect_exact('example: print -> stdout')
+    dut.expect_exact('example: print -> stderr')
+
+    # Find device with Espressif TinyUSB VID/PID
+    sleep(2)  # Some time for the OS to enumerate our USB device
+    ports = comports()
+    for port, _, hwid in ports:
+        if '303A:4001' in hwid:
+            with Serial(port) as s:
+                # Assert TinyUSB output: Read 3 lines and check their content
+                serial_output = list()
+                serial_output.append(s.readline())
+                serial_output.append(s.readline())
+                serial_output.append(s.readline())
+                assert any(b'example: log -> USB' in out for out in serial_output)
+                assert any(b'example: print -> stdout' in out for out in serial_output)
+                assert any(b'example: print -> stderr' in out for out in serial_output)
+            return
+
+    raise Exception('TinyUSB COM port not found')

examples/peripherals/usb/device/tusb_hid/pytest_usb_device_hid.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: CC0-1.0
+import pytest
+from pytest_embedded import Dut
+
+
+@pytest.mark.esp32s2
+@pytest.mark.usb_device
+def test_usb_device_hid_example(dut: Dut) -> None:
+    dut.expect_exact('USB initialization DONE')
+    dut.expect_exact('Sending Keyboard report')
+    dut.expect_exact('Sending Mouse report')

examples/peripherals/usb/device/tusb_midi/main/tusb_midi_main.c

@@ -57,6 +57,7 @@ static void periodic_midi_write_example_cb(void *arg)
     }
 
     // Send Note On for current position at full velocity (127) on channel 1.
+    ESP_LOGI(TAG, "Writing MIDI data %d", note_sequence[note_pos]);
     uint8_t note_on[3] = {0x90 | channel, note_sequence[note_pos], 127};
     tud_midi_stream_write(cable_num, note_on, 3);
 

examples/peripherals/usb/device/tusb_midi/pytest_usb_device_midi.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: CC0-1.0
+import pytest
+from pytest_embedded import Dut
+
+
+@pytest.mark.esp32s2
+@pytest.mark.usb_device
+def test_usb_device_midi_example(dut: Dut) -> None:
+    dut.expect_exact('USB initialization DONE')
+    dut.expect_exact('MIDI write task init')
+    dut.expect_exact('MIDI read task init')
+    dut.expect_exact('Writing MIDI data 74')

examples/peripherals/usb/device/tusb_sample_descriptor/CMakeLists.txt

@@ -1,6 +0,0 @@
-# The following five lines of boilerplate have to be in your project's
-# CMakeLists in this exact order for cmake to work correctly
-cmake_minimum_required(VERSION 3.16)
-
-include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-project(tusb_sample_descriptor)

examples/peripherals/usb/device/tusb_sample_descriptor/README.md

@@ -1,123 +0,0 @@
-| 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 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.
-
-## How to use example
-
-### Hardware Required
-
-Any ESP boards that have USB-OTG supported.
-
-#### Pin Assignment
-
-See common pin assignments for USB Device examples from [upper level](../../README.md#common-pin-assignments).
-
-### Configure the project
-
-There are two ways to set up a descriptor - using Menuconfig tool and in-code
-
-#### In-code setting up
-
-For the manual descriptor configuration use the default example's settings and modify `my_descriptor` in [source code](main/tusb_sample_descriptor_main.c) according to your needs
-
-#### Menuconfig
-
-If you want to set up the descriptor using Menuconfig UI:
-
-1. Execute in the terminal from the example's directory: `idf.py menuconfig`
-
-2. Turn off `Set up a USB descriptor manually in code` parameter at `Example Configuration`
-
-3. Follow `Component config -> TinyUSB -> Descriptor configuration` for all available configurations.
-
-### Build and Flash
-
-Build the project and flash it to the board, then run monitor tool to view serial output:
-
-```bash
-idf.py -p PORT flash monitor
-```
-
-(Replace PORT with the name of the serial port to use.)
-
-(To exit the serial monitor, type ``Ctrl-]``.)
-
-See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
-
-## Example Output
-
-After the flashing you should see the output:
-
-```
-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)
-```

examples/peripherals/usb/device/tusb_sample_descriptor/main/CMakeLists.txt

@@ -1,2 +0,0 @@
-idf_component_register(SRCS "tusb_sample_descriptor_main.c"
-                       INCLUDE_DIRS .)

examples/peripherals/usb/device/tusb_sample_descriptor/main/Kconfig.projbuild

@@ -1,10 +0,0 @@
-menu "Example Configuration"
-
-    config EXAMPLE_MANUAL_DESC
-        bool "Set up a USB descriptor manually in code"
-        default y
-        help
-            You can set up a descriptor using Menuconfig or independently of
-            your project configuration - manually in code
-
-endmenu

examples/peripherals/usb/device/tusb_sample_descriptor/main/tusb_sample_descriptor_main.c

@@ -1,70 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Unlicense OR CC0-1.0
- */
-
-#include <stdlib.h>
-#include "esp_log.h"
-#include "driver/gpio.h"
-#include "freertos/FreeRTOS.h"
-#include "freertos/task.h"
-#include "tinyusb.h"
-#include "sdkconfig.h"
-
-static const char *TAG = "example";
-
-void app_main(void)
-{
-    ESP_LOGI(TAG, "USB initialization");
-
-#if CONFIG_EXAMPLE_MANUAL_DESC
-    // Setting of descriptor. You can use descriptor_tinyusb and
-    // descriptor_str_tinyusb as a reference
-    tusb_desc_device_t my_descriptor = {
-        .bLength = sizeof(my_descriptor),
-        .bDescriptorType = TUSB_DESC_DEVICE,
-        .bcdUSB = 0x0200, // USB version. 0x0200 means version 2.0
-        .bDeviceClass = TUSB_CLASS_UNSPECIFIED,
-        .bMaxPacketSize0 = CFG_TUD_ENDPOINT0_SIZE,
-
-        .idVendor = 0x303A,
-        .idProduct = 0x3000,
-        .bcdDevice = 0x0101, // Device FW version
-
-        .iManufacturer = 0x01, // see string_descriptor[1] bellow
-        .iProduct = 0x02,      // see string_descriptor[2] bellow
-        .iSerialNumber = 0x03, // see string_descriptor[3] bellow
-
-        .bNumConfigurations = 0x01
-    };
-
-    tusb_desc_strarray_device_t my_string_descriptor = {
-        // array of pointer to string descriptors
-        (char[]){0x09, 0x04}, // 0: is supported language is English (0x0409)
-        "I",                  // 1: Manufacturer
-        "My Custom Device",   // 2: Product
-        "012-345",            // 3: Serials, should use chip ID
-    };
-
-    const tinyusb_config_t tusb_cfg = {
-        .descriptor = &my_descriptor,
-        .string_descriptor = my_string_descriptor,
-        .external_phy = false,
-        .configuration_descriptor = NULL,
-    };
-
-#else
-
-    const tinyusb_config_t tusb_cfg = {
-        .device_descriptor = NULL,
-        .string_descriptor = NULL,
-        .external_phy = false,
-        .configuration_descriptor = NULL,
-    };
-
-#endif
-
-    ESP_ERROR_CHECK(tinyusb_driver_install(&tusb_cfg));
-    ESP_LOGI(TAG, "USB initialization DONE");
-}

examples/peripherals/usb/device/tusb_sample_descriptor/sdkconfig.defaults

@@ -1,5 +0,0 @@
-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

examples/peripherals/usb/device/tusb_serial_device/pytest_usb_device_serial.py

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: CC0-1.0
+from time import sleep
+
+import pytest
+from pytest_embedded import Dut
+from serial import Serial
+from serial.tools.list_ports import comports
+
+
+@pytest.mark.esp32s2
+@pytest.mark.usb_device
+def test_usb_device_serial_example(dut: Dut) -> None:
+    dut.expect_exact('USB initialization DONE')
+    sleep(2)  # Some time for the OS to enumerate our USB device
+
+    # Find device with Espressif TinyUSB VID/PID
+    ports = comports()
+    for port, _, hwid in ports:
+        if '303A:4001' in hwid:
+            with Serial(port) as s:
+                s.write('text\r\n'.encode())  # Write dummy text to COM port
+                dut.expect_exact('Data from channel 0:')  # Check ESP log
+                dut.expect_exact('|text..|')
+                res = s.readline()  # Check COM echo
+                assert b'text\r\n' in res
+            return
+
+    raise Exception('TinyUSB COM port not found')

pytest.ini

@@ -37,6 +37,7 @@ markers =
   quad_psram: runners with quad psram
   octal_psram: runners with octal psram
   usb_host: usb host runners
+  usb_device: usb device runners
   ethernet_ota: ethernet OTA runners
   flash_encryption: Flash Encryption runners
   flash_encryption_f4r8: Flash Encryption runners with 4-line flash and 8-line psram

tools/ci/check_copyright_config.yaml

@@ -143,7 +143,9 @@ tinyusb:
     - 'examples/peripherals/usb/device/tusb_midi/'
   allowed_licenses:
     - Apache-2.0
-    - MIT
+    - MIT           # Example derived from TinyUSB code by HaThach
+    - Unlicense
+    - CC0-1.0
 
 # files matching this section do not perform the check
 # file patterns starting with ! are negated, meaning files matching them won't match the section.