Merge branch 'feat/add_self_power_device_example' into 'master'

feat(usb): add self powered device config

Closes AEG-508

See merge request ae_group/esp-iot-solution!1350

Author: YanKE01

.gitlab/ci/build.yml

@@ -869,20 +869,15 @@ build_example_usb_device_usb_msc_wireless_disk:
   extends:
     - .build_examples_template
     - .rules:build:example_usb_device_usb_msc_wireless_disk
-  parallel:
-    matrix:
-      - IMAGE: espressif/idf:release-v4.4
-      - IMAGE: espressif/idf:release-v5.0
+    - .build_idf_version_greater_equal_v5_0
   variables:
     EXAMPLE_DIR: examples/usb/device/usb_msc_wireless_disk
 
 build_example_usb_device_usb_surface_dial:
   extends:
     - .build_examples_template
     - .rules:build:example_usb_device_usb_surface_dial
-  parallel:
-    matrix:
-      - IMAGE: espressif/idf:release-v5.0
+    - .build_idf_version_greater_equal_v5_0
   variables:
     EXAMPLE_DIR: examples/usb/device/usb_surface_dial
 

docs/en/usb/usb_overview/usb_device_self_power.rst

@@ -59,15 +59,6 @@ The internal USB PHY of ESP32S2/S3 does not support hardware detection logic, th
 .. code-block:: C
 
        #define VBUS_MONITORING_GPIO_NUM GPIO_NUM_4
-       // Configure GPIO Pin for vbus monitoring
-       const gpio_config_t vbus_gpio_config = {
-           .pin_bit_mask = BIT64(VBUS_MONITORING_GPIO_NUM),
-           .mode = GPIO_MODE_INPUT,
-           .intr_type = GPIO_INTR_DISABLE,
-           .pull_up_en = false,
-           .pull_down_en = false,
-       };
-       ESP_ERROR_CHECK(gpio_config(&vbus_gpio_config));
        const tinyusb_config_t tusb_cfg = {
            .device_descriptor = &descriptor_config,
            .string_descriptor = string_desc_arr,
@@ -78,3 +69,11 @@ The internal USB PHY of ESP32S2/S3 does not support hardware detection logic, th
            .vbus_monitor_io = VBUS_MONITORING_GPIO_NUM,
        };
        ESP_ERROR_CHECK(tinyusb_driver_install(&tusb_cfg));
+
+If you are using native TinyUSB development, you need to configure this during the PHY initialization stage:
+
+.. code-block:: C
+
+    const usb_phy_otg_io_conf_t otg_io_conf = USB_PHY_SELF_POWERED_DEVICE(VBUS_MONITORING_GPIO_NUM);
+    phy_conf.otg_io_conf = &otg_io_conf;
+    usb_new_phy(&phy_conf, &s_phy_hdl);

docs/zh_CN/usb/usb_overview/usb_device_self_power.rst

@@ -59,15 +59,6 @@ USB 设备 VBUS 检测方法一般有两种方法：由 USB PHY 硬件检测，
 .. code-block:: C
 
        #define VBUS_MONITORING_GPIO_NUM GPIO_NUM_4
-       // Configure GPIO Pin for vbus monitoring
-       const gpio_config_t vbus_gpio_config = {
-           .pin_bit_mask = BIT64(VBUS_MONITORING_GPIO_NUM),
-           .mode = GPIO_MODE_INPUT,
-           .intr_type = GPIO_INTR_DISABLE,
-           .pull_up_en = false,
-           .pull_down_en = false,
-       };
-       ESP_ERROR_CHECK(gpio_config(&vbus_gpio_config));
        const tinyusb_config_t tusb_cfg = {
            .device_descriptor = &descriptor_config,
            .string_descriptor = string_desc_arr,
@@ -78,3 +69,11 @@ USB 设备 VBUS 检测方法一般有两种方法：由 USB PHY 硬件检测，
            .vbus_monitor_io = VBUS_MONITORING_GPIO_NUM,
        };
        ESP_ERROR_CHECK(tinyusb_driver_install(&tusb_cfg));
+
+若使用原生 TinyUSB 开发，则需要在 Phy 初始化阶段进行配置：
+
+.. code-block:: C
+
+    const usb_phy_otg_io_conf_t otg_io_conf = USB_PHY_SELF_POWERED_DEVICE(VBUS_MONITORING_GPIO_NUM);
+    phy_conf.otg_io_conf = &otg_io_conf;
+    usb_new_phy(&phy_conf, &s_phy_hdl);

examples/usb/device/usb_msc_wireless_disk/main/Kconfig.projbuild

@@ -141,4 +141,21 @@ menu "USB MSC Device Demo"
             Set the Maximum retry to avoid station reconnecting to the softAP unlimited when the softAP is really inexistent.
     endmenu
 
+    config SELF_POWERED_DEVICE
+        bool "Self-powered device"
+        default n
+        help
+            Select 'y' if the device is self-powered and does not draw power from USB VBUS.
+
+    config VBUS_MONITOR_IO
+        int "VBUS monitor GPIO number"
+        depends on SELF_POWERED_DEVICE
+        range 0 46 if IDF_TARGET_ESP32S2
+        range 0 48 if IDF_TARGET_ESP32S3
+        default 2
+        help
+            Connect VBUS to a voltage comparator chip/circuit that can detect
+            the thresholds (4.35 V and 4.75 V) and output a 3.3 V logic level
+            to the ESP32-S2/S3, indicating whether VBUS is valid.
+
 endmenu

examples/usb/device/usb_msc_wireless_disk/main/app_main.c

@@ -1,4 +1,4 @@
-/* SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+/* SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -169,7 +169,19 @@ void app_main(void)
 
     ESP_LOGI(TAG, "USB MSC initialization");
 
-    const tinyusb_config_t tusb_cfg = {0};
+    tinyusb_config_t tusb_cfg = {0};
+
+#if CONFIG_SELF_POWERED_DEVICE
+    tusb_cfg.self_powered = true;
+    tusb_cfg.vbus_monitor_io = CONFIG_VBUS_MONITOR_IO;
+
+    static const uint8_t descriptor_fs_cfg[] = {
+        // Configuration number, interface count, string index, total length, attribute, power in mA
+        TUD_CONFIG_DESCRIPTOR(1, 1, 0, (TUD_CONFIG_DESC_LEN + CFG_TUD_MSC * TUD_MSC_DESC_LEN), TUSB_DESC_CONFIG_ATT_SELF_POWERED, 100),
+        TUD_MSC_DESCRIPTOR(0, 4, 0x01, 0x81, 64),
+    };
+    tusb_cfg.configuration_descriptor = descriptor_fs_cfg;
+#endif
 
     ESP_ERROR_CHECK(tinyusb_driver_install(&tusb_cfg));
     ESP_LOGI(TAG, "USB MSC initialization DONE");

examples/usb/device/usb_msc_wireless_disk/main/idf_component.yml

@@ -1,11 +1,11 @@
 ## IDF Component Manager Manifest File
 dependencies:
   espressif/esp_tinyusb:
-    version: "~1.1.0"
+    version: "^1.7.6~1"
     rules:
       - if: "idf_version >=5.0"
-  idf: ">=4.4.0"
+  idf: ">=5.0"
   espressif/esp32_s3_usb_otg:
-    version: "^1.5.1"
+    version: "^2.0.0"
     rules:
       - if: "target in [esp32s3]"

examples/usb/device/usb_surface_dial/main/Kconfig.projbuild

@@ -21,4 +21,21 @@ menu "Example Configuration"
 
     endchoice
 
+    config SELF_POWERED_DEVICE
+        bool "Self-powered device"
+        default n
+        help
+            Select 'y' if the device is self-powered and does not draw power from USB VBUS.
+
+    config VBUS_MONITOR_IO
+        int "VBUS monitor GPIO number"
+        depends on SELF_POWERED_DEVICE
+        range 0 46 if IDF_TARGET_ESP32S2
+        range 0 48 if IDF_TARGET_ESP32S3
+        default 2
+        help
+            Connect VBUS to a voltage comparator chip/circuit that can detect
+            the thresholds (4.35 V and 4.75 V) and output a 3.3 V logic level
+            to the ESP32-S2/S3, indicating whether VBUS is valid.
+
 endmenu

examples/usb/device/usb_surface_dial/main/idf_component.yml

@@ -4,16 +4,12 @@ dependencies:
   idf:
     version: ">=5.0"
   espressif/button:
-    version: ">=2.3.0"
-    override_path: "../../../../../components/button"
+    version: ">=4.1.0"
   espressif/tinyusb:
-    version: ">=0.15.0~2"
+    version: ">=0.18.0~1"
   espressif/knob:
-    version: ">=0.1.0"
-    override_path: "../../../../../components/knob"
+    version: ">=1.0.0"
   espressif/esp32_s3_usb_otg:
-    version: "^1.5.1"
+    version: ">=2.0.0"
     rules:
       - if: "target in [esp32s3]"
-  lvgl/lvgl: #temp to workaround bsp issue
-    version: "9.2.0"

examples/usb/device/usb_surface_dial/main/main.c

@@ -46,6 +46,10 @@ static void usb_phy_init(void)
         .otg_mode = USB_OTG_MODE_DEVICE,
         .target = USB_PHY_TARGET_INT,
     };
+#if CONFIG_SELF_POWERED_DEVICE
+    const usb_phy_otg_io_conf_t otg_io_conf = USB_PHY_SELF_POWERED_DEVICE(CONFIG_VBUS_MONITOR_IO);
+    phy_conf.otg_io_conf = &otg_io_conf;
+#endif
     usb_new_phy(&phy_conf, &s_phy_hdl);
 }
 
@@ -86,19 +90,19 @@ static void _knob_left_cb(void *arg, void *data)
 
 static void _button_init(void)
 {
-    button_config_t cfg = {
-        .type = BUTTON_TYPE_GPIO,
+    button_config_t btn_cfg = {
         .long_press_time = 1000,
         .short_press_time = 200,
-        .gpio_button_config = {
-            .gpio_num  = GPIO_BUTTON,
-            .active_level = 0,
-        },
     };
-    s_btn = iot_button_create(&cfg);
 
-    iot_button_register_cb(s_btn, BUTTON_PRESS_DOWN, _button_press_down_cb, NULL);
-    iot_button_register_cb(s_btn, BUTTON_PRESS_UP, _button_press_up_cb, NULL);
+    button_gpio_config_t btn_gpio_cfg = {
+        .gpio_num = GPIO_BUTTON,
+        .active_level = 0,
+    };
+
+    ESP_ERROR_CHECK(iot_button_new_gpio_device(&btn_cfg, &btn_gpio_cfg, &s_btn));
+    iot_button_register_cb(s_btn, BUTTON_PRESS_DOWN, NULL,  _button_press_down_cb, NULL);
+    iot_button_register_cb(s_btn, BUTTON_PRESS_UP, NULL, _button_press_up_cb, NULL);
 }
 
 static void _knob_init(void)

examples/usb/device/usb_surface_dial/main/usb_descriptors.c

@@ -130,7 +130,11 @@ enum {
 
 uint8_t const desc_configuration[] = {
     // Config number, interface count, string index, total length, attribute, power in mA
+#if CONFIG_SELF_POWERED_DEVICE
+    TUD_CONFIG_DESCRIPTOR(1, ITF_NUM_TOTAL, 0, CONFIG_TOTAL_LEN, TUSB_DESC_CONFIG_ATT_SELF_POWERED, 100),
+#else
     TUD_CONFIG_DESCRIPTOR(1, ITF_NUM_TOTAL, 0, CONFIG_TOTAL_LEN, 0, 100),
+#endif
 
     // Interface number, string index, protocol, report descriptor len, EP In address, size & polling interval
     TUD_HID_DESCRIPTOR(ITF_NUM_HID, 4, HID_ITF_PROTOCOL_NONE, sizeof(desc_hid_report), EPNUM_HID, CFG_TUD_HID_EP_BUFSIZE, 10),