usb: Add USB Host Library Example

The commit adds a basic example for the USB Host Library

examples/peripherals/usb/host/usb_host_lib/CMakeLists.txt

@@ -0,0 +1,6 @@
+# The following 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.5)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(usb_host_lib_example)

examples/peripherals/usb/host/usb_host_lib/README.md

@@ -0,0 +1,182 @@
+| Supported Targets | ESP32-S2 | ESP32-S3 |
+| ----------------- | -------- | -------- |
+
+# USB Host Library Example
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example demonstrates the basic usage of the [USB Host Library API](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/usb_host.html) by implementing a pseudo class driver and a Host Library daemon task. The example does the following:
+
+1. Install Host Library and register a client
+2. Waits for a device connection
+3. Prints the device's information (such as device/configuration/string descriptors)
+4. Waits for the device to disconnect
+5. Deregister the client and uninstall the Host Library
+
+The example demonstrates the following aspects of the USB Host Library API:
+
+- How to use the Library API to:
+    - Install and uninstall the USB Host Library
+    - Run the library event handler function a daemon task
+    - How to handle library events
+- How to use the Client API from a client task to:
+    - Register and deregister a client of the USB Host Library
+    - Run the client event handler functions
+    - How to handle client events via various callbacks
+    - Open and close a device
+    - Get a device's descriptors
+
+## How to use example
+
+### Hardware Required
+
+An ESP board that supports USB-OTG. The example uses the ESP's internal USB PHY, however the internal USB PHY's pins will need to be connected to a USB port (i.e., a USB breakout board) as follows:
+
+- GND and 5V signals of the ESP board to the GND and 5V lines of the USB port
+- GPIO 19 to D-
+- GPIO 20 to D+
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+
+* The USB Host Stack has a maximum supported transfer size for control transfer during device enumeration. This size is specified via the USB_HOST_CONTROL_TRANSFER_MAX_SIZE configuration option and has a default value of 256 bytes. Therefore, if devices with length config/string descriptors are used, users may want to increase the size of this configuration.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+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
+
+```
+I (261) cpu_start: Starting scheduler on PRO CPU.
+I (267) DAEMON: Installing USB Host Library
+I (297) CLASS: Registering Client
+I (5067) CLASS: Opening device at address 1
+I (5067) CLASS: Getting device information
+I (5067) CLASS: 	Full speed
+I (5067) CLASS: 	bConfigurationValue 1
+I (5067) CLASS: Getting device descriptor
+*** Device descriptor ***
+bLength 18
+bDescriptorType 1
+bcdUSB 2.00
+bDeviceClass 0xef
+bDeviceSubClass 0x2
+bDeviceProtocol 0x1
+bMaxPacketSize0 64
+idVendor 0x303a
+idProduct 0x1001
+bcdDevice 1.00
+iManufacturer 1
+iProduct 2
+iSerialNumber 3
+bNumConfigurations 1
+I (5097) CLASS: Getting config descriptor
+*** Configuration descriptor ***
+bLength 9
+bDescriptorType 2
+wTotalLength 98
+bNumInterfaces 3
+bConfigurationValue 1
+iConfiguration 0
+bmAttributes 0xc0
+bMaxPower 500mA
+	*** Interface descriptor ***
+	bLength 9
+	bDescriptorType 4
+	bInterfaceNumber 0
+	bAlternateSetting 0
+	bNumEndpoints 1
+	bInterfaceClass 0x0
+	iInterface 0
+		*** Endpoint descriptor ***
+		bLength 7
+		bDescriptorType 5
+		bEndpointAddress 0x82	EP 2 IN
+		bmAttributes 0x3	INT
+		wMaxPacketSize 64
+		bInterval 1
+	*** Interface descriptor ***
+	bLength 9
+	bDescriptorType 4
+	bInterfaceNumber 1
+	bAlternateSetting 0
+	bNumEndpoints 2
+	bInterfaceClass 0x0
+	iInterface 0
+		*** Endpoint descriptor ***
+		bLength 7
+		bDescriptorType 5
+		bEndpointAddress 0x1	EP 1 OUT
+		bmAttributes 0x2	BULK
+		wMaxPacketSize 64
+		bInterval 1
+		*** Endpoint descriptor ***
+		bLength 7
+		bDescriptorType 5
+		bEndpointAddress 0x81	EP 1 IN
+		bmAttributes 0x2	BULK
+		wMaxPacketSize 64
+		bInterval 1
+	*** Interface descriptor ***
+	bLength 9
+	bDescriptorType 4
+	bInterfaceNumber 2
+	bAlternateSetting 0
+	bNumEndpoints 2
+	bInterfaceClass 0x1
+	iInterface 0
+		*** Endpoint descriptor ***
+		bLength 7
+		bDescriptorType 5
+		bEndpointAddress 0x2	EP 2 OUT
+		bmAttributes 0x2	BULK
+		wMaxPacketSize 64
+		bInterval 1
+		*** Endpoint descriptor ***
+		bLength 7
+		bDescriptorType 5
+		bEndpointAddress 0x83	EP 3 IN
+		bmAttributes 0x2	BULK
+		wMaxPacketSize 64
+		bInterval 1
+I (5227) CLASS: Getting Manufacturer string descriptor
+Espressif
+I (5237) CLASS: Getting Product string descriptor
+USB JTAG/serial debug unit
+I (5247) CLASS: Getting Serial Number string descriptor
+7C:DF:A1:E0:10:50
+```
+
+## Troubleshooting
+
+To obtain more debug, users should set the [log level](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/system/log.html) to debug via menuconfig.
+
+### Failing Enumeration
+
+```
+I (262) cpu_start: Starting scheduler on PRO CPU.
+I (268) DAEMON: Installing USB Host Library
+I (298) CLASS: Registering Client
+E (2748) HUB: Short string desc corrupt
+E (2748) HUB: Stage failed: CHECK_SHORT_MANU_STR_DESC
+```
+
+The log output demonstrates a device that has failed. The Hub Driver will output some error logs indicating which stage of enumeration has failed.
+
+### Blank String Descriptors
+
+The current USB Host Library will automatically cache the Manufacturer, Product, and Serial Number string descriptors of the device during enumeration. However, when fetching the string descriptors, the USB Host Library will only fetch those strings descriptors of they of LANGID code 0x0409 (i.e., English - United States). Therefore, if the example does not print a particular descriptor, it is likely that the string descriptor was not cached during enumeration.

examples/peripherals/usb/host/usb_host_lib/main/CMakeLists.txt

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

examples/peripherals/usb/host/usb_host_lib/main/class_driver.c

@@ -0,0 +1,188 @@
+/*
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+#include <stdlib.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+#include "esp_log.h"
+#include "usb/usb_host.h"
+
+#define CLIENT_NUM_EVENT_MSG        5
+
+#define ACTION_OPEN_DEV             0x01
+#define ACTION_GET_DEV_INFO         0x02
+#define ACTION_GET_DEV_DESC         0x04
+#define ACTION_GET_CONFIG_DESC      0x08
+#define ACTION_GET_STR_DESC         0x10
+#define ACTION_CLOSE_DEV            0x20
+#define ACTION_EXIT                 0x40
+
+typedef struct {
+    usb_host_client_handle_t client_hdl;
+    uint8_t dev_addr;
+    usb_device_handle_t dev_hdl;
+    uint32_t actions;
+} class_driver_t;
+
+static const char *TAG = "CLASS";
+
+static void client_event_cb(const usb_host_client_event_msg_t *event_msg, void *arg)
+{
+    class_driver_t *driver_obj = (class_driver_t *)arg;
+    switch (event_msg->event) {
+        case USB_HOST_CLIENT_EVENT_NEW_DEV:
+            if (driver_obj->dev_addr == 0) {
+                driver_obj->dev_addr = event_msg->new_dev.address;
+                //Open the device next
+                driver_obj->actions |= ACTION_OPEN_DEV;
+            }
+            break;
+        case USB_HOST_CLIENT_EVENT_DEV_GONE:
+            if (driver_obj->dev_hdl != NULL) {
+                //Cancel any other actions and close the device next
+                driver_obj->actions = ACTION_CLOSE_DEV;
+            }
+            break;
+        default:
+            //Should never occur
+            abort();
+    }
+}
+
+static void action_open_dev(class_driver_t *driver_obj)
+{
+    assert(driver_obj->dev_addr != 0);
+    ESP_LOGI(TAG, "Opening device at address %d", driver_obj->dev_addr);
+    ESP_ERROR_CHECK(usb_host_device_open(driver_obj->client_hdl, driver_obj->dev_addr, &driver_obj->dev_hdl));
+    //Get the device's information next
+    driver_obj->actions &= ~ACTION_OPEN_DEV;
+    driver_obj->actions |= ACTION_GET_DEV_INFO;
+}
+
+static void action_get_info(class_driver_t *driver_obj)
+{
+    assert(driver_obj->dev_hdl != NULL);
+    ESP_LOGI(TAG, "Getting device information");
+    usb_device_info_t dev_info;
+    ESP_ERROR_CHECK(usb_host_device_info(driver_obj->dev_hdl, &dev_info));
+    ESP_LOGI(TAG, "\t%s speed", (dev_info.speed == USB_SPEED_LOW) ? "Low" : "Full");
+    ESP_LOGI(TAG, "\tbConfigurationValue %d", dev_info.bConfigurationValue);
+    //Todo: Print string descriptors
+
+    //Get the device descriptor next
+    driver_obj->actions &= ~ACTION_GET_DEV_INFO;
+    driver_obj->actions |= ACTION_GET_DEV_DESC;
+}
+
+static void action_get_dev_desc(class_driver_t *driver_obj)
+{
+    assert(driver_obj->dev_hdl != NULL);
+    ESP_LOGI(TAG, "Getting device descriptor");
+    const usb_device_desc_t *dev_desc;
+    ESP_ERROR_CHECK(usb_host_get_device_descriptor(driver_obj->dev_hdl, &dev_desc));
+    usb_print_device_descriptor(dev_desc);
+    //Get the device's config descriptor next
+    driver_obj->actions &= ~ACTION_GET_DEV_DESC;
+    driver_obj->actions |= ACTION_GET_CONFIG_DESC;
+}
+
+static void action_get_config_desc(class_driver_t *driver_obj)
+{
+    assert(driver_obj->dev_hdl != NULL);
+    ESP_LOGI(TAG, "Getting config descriptor");
+    const usb_config_desc_t *config_desc;
+    ESP_ERROR_CHECK(usb_host_get_active_config_descriptor(driver_obj->dev_hdl, &config_desc));
+    usb_print_config_descriptor(config_desc, NULL);
+    //Get the device's string descriptors next
+    driver_obj->actions &= ~ACTION_GET_CONFIG_DESC;
+    driver_obj->actions |= ACTION_GET_STR_DESC;
+}
+
+static void action_get_str_desc(class_driver_t *driver_obj)
+{
+    assert(driver_obj->dev_hdl != NULL);
+    usb_device_info_t dev_info;
+    ESP_ERROR_CHECK(usb_host_device_info(driver_obj->dev_hdl, &dev_info));
+    if (dev_info.str_desc_manufacturer) {
+        ESP_LOGI(TAG, "Getting Manufacturer string descriptor");
+        usb_print_string_descriptor(dev_info.str_desc_manufacturer);
+    }
+    if (dev_info.str_desc_product) {
+        ESP_LOGI(TAG, "Getting Product string descriptor");
+        usb_print_string_descriptor(dev_info.str_desc_product);
+    }
+    if (dev_info.str_desc_serial_num) {
+        ESP_LOGI(TAG, "Getting Serial Number string descriptor");
+        usb_print_string_descriptor(dev_info.str_desc_serial_num);
+    }
+    //Nothing to do until the device disconnects
+    driver_obj->actions &= ~ACTION_GET_STR_DESC;
+}
+
+static void aciton_close_dev(class_driver_t *driver_obj)
+{
+    ESP_ERROR_CHECK(usb_host_device_close(driver_obj->client_hdl, driver_obj->dev_hdl));
+    driver_obj->dev_hdl = NULL;
+    driver_obj->dev_addr = 0;
+    //We need to exit the event handler loop
+    driver_obj->actions &= ~ACTION_CLOSE_DEV;
+    driver_obj->actions |= ACTION_EXIT;
+}
+
+void class_driver_task(void *arg)
+{
+    SemaphoreHandle_t signaling_sem = (SemaphoreHandle_t)arg;
+    class_driver_t driver_obj = {0};
+
+    //Wait until daemon task has installed USB Host Library
+    xSemaphoreTake(signaling_sem, portMAX_DELAY);
+
+    ESP_LOGI(TAG, "Registering Client");
+    usb_host_client_config_t client_config = {
+        .is_synchronous = false,    //Synchronous clients currently not supported. Set this to false
+        .max_num_event_msg = CLIENT_NUM_EVENT_MSG,
+        .async = {
+            .client_event_callback = client_event_cb,
+            .callback_arg = (void *)&driver_obj,
+        },
+    };
+    ESP_ERROR_CHECK(usb_host_client_register(&client_config, &driver_obj.client_hdl));
+
+    while (1) {
+        if (driver_obj.actions == 0) {
+            usb_host_client_handle_events(driver_obj.client_hdl, portMAX_DELAY);
+        } else {
+            if (driver_obj.actions & ACTION_OPEN_DEV) {
+                action_open_dev(&driver_obj);
+            }
+            if (driver_obj.actions & ACTION_GET_DEV_INFO) {
+                action_get_info(&driver_obj);
+            }
+            if (driver_obj.actions & ACTION_GET_DEV_DESC) {
+                action_get_dev_desc(&driver_obj);
+            }
+            if (driver_obj.actions & ACTION_GET_CONFIG_DESC) {
+                action_get_config_desc(&driver_obj);
+            }
+            if (driver_obj.actions & ACTION_GET_STR_DESC) {
+                action_get_str_desc(&driver_obj);
+            }
+            if (driver_obj.actions & ACTION_CLOSE_DEV) {
+                aciton_close_dev(&driver_obj);
+            }
+            if (driver_obj.actions & ACTION_EXIT) {
+                break;
+            }
+        }
+    }
+
+    ESP_LOGI(TAG, "Deregistering Client");
+    ESP_ERROR_CHECK(usb_host_client_deregister(driver_obj.client_hdl));
+
+    //Wait to be deleted
+    xSemaphoreGive(signaling_sem);
+    vTaskSuspend(NULL);
+}

examples/peripherals/usb/host/usb_host_lib/main/usb_host_lib_main.c

@@ -0,0 +1,90 @@
+/*
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include "esp_log.h"
+#include "esp_intr_alloc.h"
+#include "usb/usb_host.h"
+
+#define DAEMON_TASK_PRIORITY    2
+#define CLASS_TASK_PRIORITY     3
+
+extern void class_driver_task(void *arg);
+
+static const char *TAG = "DAEMON";
+
+static void host_lib_daemon_task(void *arg)
+{
+    SemaphoreHandle_t signaling_sem = (SemaphoreHandle_t)arg;
+
+    ESP_LOGI(TAG, "Installing USB Host Library");
+    usb_host_config_t host_config = {
+        .skip_phy_setup = false,
+        .intr_flags = ESP_INTR_FLAG_LEVEL1,
+    };
+    ESP_ERROR_CHECK(usb_host_install(&host_config));
+
+    //Signal to the class driver task that the host library is installed
+    xSemaphoreGive(signaling_sem);
+    vTaskDelay(10); //Short delay to let client task spin up
+
+    bool has_clients = true;
+    bool has_devices = true;
+    while (has_clients || has_devices ) {
+        uint32_t event_flags;
+        ESP_ERROR_CHECK(usb_host_lib_handle_events(portMAX_DELAY, &event_flags));
+        if (event_flags & USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS) {
+            has_clients = false;
+        }
+        if (event_flags & USB_HOST_LIB_EVENT_FLAGS_ALL_FREE) {
+            has_devices = false;
+        }
+    }
+    ESP_LOGI(TAG, "No more clients and devices");
+
+    //Uninstall the USB Host Library
+    ESP_ERROR_CHECK(usb_host_uninstall());
+    //Wait to be deleted
+    xSemaphoreGive(signaling_sem);
+    vTaskSuspend(NULL);
+}
+
+void app_main(void)
+{
+    SemaphoreHandle_t signaling_sem = xSemaphoreCreateBinary();
+
+    TaskHandle_t daemon_task_hdl;
+    TaskHandle_t class_driver_task_hdl;
+    //Create daemon task
+    xTaskCreatePinnedToCore(host_lib_daemon_task,
+                            "daemon",
+                            4096,
+                            (void *)signaling_sem,
+                            DAEMON_TASK_PRIORITY,
+                            &daemon_task_hdl,
+                            0);
+    //Create the class driver task
+    xTaskCreatePinnedToCore(class_driver_task,
+                            "class",
+                            4096,
+                            (void *)signaling_sem,
+                            CLASS_TASK_PRIORITY,
+                            &class_driver_task_hdl,
+                            0);
+
+    vTaskDelay(10);     //Add a short delay to let the tasks run
+
+    //Wait for the tasks to complete
+    for (int i = 0; i < 2; i++) {
+        xSemaphoreTake(signaling_sem, portMAX_DELAY);
+    }
+
+    //Delete the tasks
+    vTaskDelete(class_driver_task_hdl);
+    vTaskDelete(daemon_task_hdl);
+}