Merge branch 'feat/hid_example_supports_p4' into 'master'

feat(usb_device): hid example supports esp32p4

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

Author: YanKE01

.gitlab/ci/build.yml

@@ -851,9 +851,7 @@ build_example_usb_device_usb_hid_device:
   extends:
     - .build_examples_template
     - .rules:build:example_usb_device_usb_hid_device
-  parallel:
-    matrix:
-      - IMAGE: espressif/idf:release-v5.0
+    - .build_idf_version_greater_equal_v5_0
   variables:
     EXAMPLE_DIR: examples/usb/device/usb_hid_device
 

examples/usb/device/usb_hid_device/README.md

@@ -1,6 +1,6 @@
 ## USB HID Device example
 
-This example demonstrates how to use ESP32-Sx USB function as the HID device. Buttons are used to trigger such signals as a keyboard or mouse.
+This example demonstrates how to use ESP32-S2/S3/P4 USB function as the HID device. Buttons are used to trigger such signals as a keyboard or mouse.
 
 * Supports traditional six-key keyboard mode
 * Supports full key no-conflict keyboard mode
@@ -9,17 +9,21 @@ This example demonstrates how to use ESP32-Sx USB function as the HID device. Bu
 
 ### Hardware Required
 
-- Any ESP32-S2 or ESP32-S3 development board with **buttons**
+- Any ESP32-S2/S3/P4 development board with **buttons**
 
 - Hardware Connection：
-  - GPIO19 to D
-  - GPIO20 to D+
+
+|              | USB_DP | USB_DM |
+| ------------ | ------ | ------ |
+| ESP32-S2/S3  | GPIO20 | GPIO19 |
+| ESP32-P4 2.0 | pin 50 | pin 49 |
+| ESP32-P4 1.1 | GPIO27 | GPIO26 |
 
 ### Configure the project
 
 By default the buttons act as a mouse, you can use `idf.py menuconfig` change `USB HID Device Demo->hid class subclass` to `keyboard`.
 
-![](_static/choose_subclass.png)
+![](https://dl.espressif.com/AE/esp-iot-solution/usb_hid_device_choose_subclass.png)
 
 ### Build and Flash
 
@@ -31,7 +35,7 @@ By default the buttons act as a mouse, you can use `idf.py menuconfig` change `U
     . $HOME/esp/esp-idf/export.sh
     ```
 
-3. Set ESP-IDF build target to `esp32s2` or `esp32s3`
+3. Set ESP-IDF build target to `esp32s2` or `esp32s3` or `esp32p4`
 
     ```bash
     idf.py set-target esp32s2

examples/usb/device/usb_hid_device/_static/choose_subclass.png

@@ -32,18 +32,10 @@
 extern "C" {
 #endif
 
-//--------------------------------------------------------------------+
-// Board Specific Configuration
-//--------------------------------------------------------------------+
-
-// RHPort number used for device can be defined by board.mk, default to port 0
-#ifndef BOARD_TUD_RHPORT
-#define BOARD_TUD_RHPORT      0
-#endif
-
-// RHPort max operational speed can defined by board.mk
-#ifndef BOARD_TUD_MAX_SPEED
-#define BOARD_TUD_MAX_SPEED   OPT_MODE_DEFAULT_SPEED
+#ifdef CONFIG_TINYUSB_RHPORT_HS
+#   define CFG_TUSB_RHPORT1_MODE    OPT_MODE_DEVICE | OPT_MODE_HIGH_SPEED
+#else
+#   define CFG_TUSB_RHPORT0_MODE    OPT_MODE_DEVICE | OPT_MODE_FULL_SPEED
 #endif
 
 //--------------------------------------------------------------------
@@ -64,7 +56,7 @@ extern "C" {
 #endif
 
 // Espressif IDF requires "freertos/" prefix in include path
-#if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3)
+#if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3, OPT_MCU_ESP32P4)
 #define CFG_TUSB_OS_INC_PATH    freertos/
 #endif
 
@@ -75,9 +67,6 @@ extern "C" {
 // Enable Device stack
 #define CFG_TUD_ENABLED       1
 
-// Default is max speed that hardware controller could support with on-chip PHY
-#define CFG_TUD_MAX_SPEED     BOARD_TUD_MAX_SPEED
-
 /* USB DMA on some MCUs can only access a specific SRAM region with restriction on alignment.
  * Tinyusb use follows macros to declare transferring memory so that they can be put
  * into those specific section.

examples/usb/device/usb_hid_device/hid_device/tusb_config.h

@@ -92,21 +92,67 @@ uint8_t const *tud_descriptor_device_cb(void)
 //--------------------------------------------------------------------+
 #define CONFIG_TOTAL_LEN    (TUD_CONFIG_DESC_LEN + TUD_HID_DESC_LEN * CFG_TUD_HID)
 
-uint8_t const desc_fs_configuration[] = {
+uint8_t const desc_configuration[] = {
     // Config number, interface count, string index, total length, attribute, power in mA
     TUD_CONFIG_DESCRIPTOR(1, ITF_NUM_TOTAL, 0, CONFIG_TOTAL_LEN, 0, 100),
     // 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), (0x80 | EPNUM_HID_DATA), CFG_TUD_HID_EP_BUFSIZE, 10)
 };
 
+#if TUD_OPT_HIGH_SPEED
+// Per USB specs: high speed capable device must report device_qualifier and other_speed_configuration
+
+// other speed configuration
+uint8_t desc_other_speed_config[CONFIG_TOTAL_LEN];
+
+// device qualifier is mostly similar to device descriptor since we don't change configuration based on speed
+tusb_desc_device_qualifier_t const desc_device_qualifier = {
+    .bLength            = sizeof(tusb_desc_device_qualifier_t),
+    .bDescriptorType    = TUSB_DESC_DEVICE_QUALIFIER,
+    .bcdUSB             = 0x0200,
+
+    .bDeviceClass       = TUSB_CLASS_MISC,
+    .bDeviceSubClass    = MISC_SUBCLASS_COMMON,
+    .bDeviceProtocol    = MISC_PROTOCOL_IAD,
+
+    .bMaxPacketSize0    = CFG_TUD_ENDPOINT0_SIZE,
+    .bNumConfigurations = 0x01,
+    .bReserved          = 0x00
+};
+
+// Invoked when received GET DEVICE QUALIFIER DESCRIPTOR request
+// Application return pointer to descriptor, whose contents must exist long enough for transfer to complete.
+// device_qualifier descriptor describes information about a high-speed capable device that would
+// change if the device were operating at the other speed. If not highspeed capable stall this request.
+uint8_t const* tud_descriptor_device_qualifier_cb(void)
+{
+    return (uint8_t const*) &desc_device_qualifier;
+}
+
+// Invoked when received GET OTHER SEED CONFIGURATION DESCRIPTOR request
+// Application return pointer to descriptor, whose contents must exist long enough for transfer to complete
+// Configuration descriptor in the other speed e.g if high speed then this is for full speed and vice versa
+uint8_t const* tud_descriptor_other_speed_configuration_cb(uint8_t index)
+{
+    (void) index; // for multiple configurations
+
+    // other speed config is basically configuration with type = OHER_SPEED_CONFIG
+    memcpy(desc_other_speed_config, desc_configuration, CONFIG_TOTAL_LEN);
+    desc_other_speed_config[1] = TUSB_DESC_OTHER_SPEED_CONFIG;
+
+    // this example use the same configuration for both high and full speed mode
+    return desc_other_speed_config;
+}
+#endif
+
 // Invoked when received GET CONFIGURATION DESCRIPTOR
 // Application return pointer to descriptor
 // Descriptor contents must exist long enough for transfer to complete
 uint8_t const *tud_descriptor_configuration_cb(uint8_t index)
 {
     (void) index; // for multiple configurations
 
-    return desc_fs_configuration;
+    return desc_configuration;
 }
 
 //--------------------------------------------------------------------+

examples/usb/device/usb_hid_device/hid_device/usb_descriptors.c

@@ -44,6 +44,21 @@ menu "USB HID Device Example"
         string "Product Name"
         default "HID Demo"
 
+    choice TINYUSB_RHPORT
+        prompt "TinyUSB Root Port"
+        default TINYUSB_RHPORT_HS if IDF_TARGET_ESP32P4
+        default TINYUSB_RHPORT_FS
+        help
+            Allows set the USB PHY Controller for TinyUSB: HS (USB OTG2.0 PHY for HighSpeed)
+
+        config TINYUSB_RHPORT_HS
+            depends on IDF_TARGET_ESP32P4
+            bool "High Speed"
+
+        config TINYUSB_RHPORT_FS
+            bool "Full Speed"
+    endchoice
+
     config ENABLE_FULL_KEY_KEYBOARD
         bool "Enable Full Key Keyboard"
         default n

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

@@ -1,10 +1,10 @@
 dependencies:
   idf: ">=5.0"
   espressif/button:
-    version: "~2.5.0"
+    version: "^4.0.0"
   espressif/tinyusb:
-    version: ">=0.15.0~2"
+    version: ">=0.18.0~1"
   espressif/esp32_s3_usb_otg:
-    version: "^1.5.1"
+    version: "^2.0.0"
     rules:
       - if: "target in [esp32s3]"

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

@@ -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
  */
@@ -9,6 +9,7 @@
 #include "esp_log.h"
 #include "sdkconfig.h"
 #include "iot_button.h"
+#include "button_gpio.h"
 #include "esp_private/usb_phy.h"
 #include "tinyusb_hid.h"
 #ifdef CONFIG_ESP32_S3_USB_OTG
@@ -31,16 +32,6 @@
 static int s_button_gpio[EXAMPLE_BUTTON_NUM] = {EXAMPLE_BUTTON_UP, EXAMPLE_BUTTON_DOWN, EXAMPLE_BUTTON_LEFT, EXAMPLE_BUTTON_RIGHT};
 static button_handle_t s_button_handles[EXAMPLE_BUTTON_NUM] = {NULL};
 
-static int get_button_gpio(button_handle_t btn_hdl)
-{
-    for (size_t i = 0; i < EXAMPLE_BUTTON_NUM; i++) {
-        if (s_button_handles[i] == btn_hdl) {
-            return s_button_gpio[i];
-        }
-    }
-    return -1;
-}
-
 #ifdef CONFIG_SUBCLASS_KEYBOARD
 #if CONFIG_ENABLE_FULL_KEY_KEYBOARD
 static uint8_t keycode[15] = {0};
@@ -93,10 +84,12 @@ static bool remove_key(uint8_t key)
     return false;
 }
 #endif
-static void button_keyboard_cb(void *arg, void *arg2)
+static void button_keyboard_cb(void *arg, void *data)
 {
-    button_handle_t button_hdl = (button_handle_t)arg;
-    int button_gpio = get_button_gpio(button_hdl);
+    int button_gpio = (int)data;
+    button_event_t event = iot_button_get_event(arg);
+    ESP_LOGI(TAG, "Button GPIO %d event %d", button_gpio, event);
+
     uint8_t key = 0;
     switch (button_gpio) {
     case EXAMPLE_BUTTON_UP:
@@ -119,7 +112,7 @@ static void button_keyboard_cb(void *arg, void *arg2)
         break;
     }
 
-    if (iot_button_get_event(button_hdl) == BUTTON_PRESS_UP) {
+    if (event == BUTTON_PRESS_UP) {
         remove_key(key);
         ESP_LOGI(TAG, "Remove Keyboard %c", key - HID_KEY_A + 'a');
     } else {
@@ -129,10 +122,11 @@ static void button_keyboard_cb(void *arg, void *arg2)
     tinyusb_hid_keyboard_report(0, keycode);
 }
 #elif defined CONFIG_SUBCLASS_MOUSE
-static void button_mouse_cb(void *arg, void *arg2)
+static void button_mouse_cb(void *arg, void *data)
 {
-    button_handle_t button_hdl = (button_handle_t)arg;
-    int button_gpio = get_button_gpio(button_hdl);
+    int button_gpio = (int)data;
+    ESP_LOGI(TAG, "Button GPIO %d", button_gpio);
+
     int mouse_offset_x = 0, mouse_offset_y = 0;
     switch (button_gpio) {
     case EXAMPLE_BUTTON_UP:
@@ -208,6 +202,9 @@ static void usb_phy_init(void)
         .controller = USB_PHY_CTRL_OTG,
         .otg_mode = USB_OTG_MODE_DEVICE,
         .target = USB_PHY_TARGET_INT,
+#if CONFIG_TINYUSB_RHPORT_HS
+        .otg_speed = USB_PHY_SPEED_HIGH,
+#endif
     };
     usb_new_phy(&phy_conf, &phy_hdl);
 }
@@ -219,46 +216,31 @@ void app_main(void)
 #endif
     // switch esp usb phy to usb-otg
     usb_phy_init();
-    tud_init(BOARD_TUD_RHPORT);
+    bool usb_init = tusb_init();
+    if (!usb_init) {
+        ESP_LOGE(TAG, "TinyUSB init failed");
+        return;
+    }
+
     xTaskCreate(tusb_device_task, "TinyUSB", 4096, NULL, 5, NULL);
     tinyusb_hid_init();
 
     /* buttons init, buttons used to simulate keyboard or mouse events */
-    button_config_t cfg = {
-        .type = BUTTON_TYPE_GPIO,
-        .gpio_button_config = {
-            .active_level = 0,
-        },
+    button_config_t btn_cfg = {0};
+    button_gpio_config_t btn_gpio_cfg = {
+        .active_level = 0,
     };
 
     for (size_t i = 0; i < EXAMPLE_BUTTON_NUM; i++) {
-        cfg.gpio_button_config.gpio_num = s_button_gpio[i];
-        s_button_handles[i] = iot_button_create(&cfg);
-        if (s_button_handles[i] == NULL) {
-            ESP_LOGE(TAG, "Button io = %d created failed", s_button_gpio[i]);
-            assert(0);
-        } else {
-            ESP_LOGI(TAG, "Button io = %d created", s_button_gpio[i]);
-        }
-    }
-
-#ifdef CONFIG_SUBCLASS_KEYBOARD
-    button_cb_t button_cb = button_keyboard_cb;
-    ESP_LOGI(TAG, "HID Keyboard demo: press button to simulate keyboard");
-#elif defined CONFIG_SUBCLASS_MOUSE
-    button_cb_t button_cb = button_mouse_cb;
-    ESP_LOGI(TAG, "HID Mouse demo: press button to simulate mouse");
-#endif
-    ESP_LOGI(TAG, "Wait Mount through USB interface");
-
-    /* register button callback, send HID report when click button */
-    for (size_t i = 0; i < EXAMPLE_BUTTON_NUM; i++) {
+        btn_gpio_cfg.gpio_num = s_button_gpio[i];
+        ESP_ERROR_CHECK(iot_button_new_gpio_device(&btn_cfg, &btn_gpio_cfg, &s_button_handles[i]));
 #ifdef CONFIG_SUBCLASS_KEYBOARD
-        iot_button_register_cb(s_button_handles[i], BUTTON_PRESS_DOWN, button_cb, NULL);
-        iot_button_register_cb(s_button_handles[i], BUTTON_PRESS_UP, button_cb, NULL);
+        ESP_ERROR_CHECK(iot_button_register_cb(s_button_handles[i], BUTTON_PRESS_UP, NULL, button_keyboard_cb, (void*)s_button_gpio[i]));
+        ESP_ERROR_CHECK(iot_button_register_cb(s_button_handles[i], BUTTON_PRESS_DOWN, NULL, button_keyboard_cb, (void*)s_button_gpio[i]));
 #elif defined CONFIG_SUBCLASS_MOUSE
-        iot_button_register_cb(s_button_handles[i], BUTTON_SINGLE_CLICK, button_cb, NULL);
+        ESP_ERROR_CHECK(iot_button_register_cb(s_button_handles[i], BUTTON_SINGLE_CLICK, NULL, button_mouse_cb, (void*)s_button_gpio[i]));
 #endif
+        ESP_LOGI(TAG, "Button io = %d created", s_button_gpio[i]);
     }
 
     while (1) {