README.md
1| Supported Targets | ESP32-S2 | ESP32-S3 |
2| ----------------- | -------- | -------- |
3
4# USB Host Library Example
5
6(See the README.md file in the upper level 'examples' directory for more information about examples.)
7
8This 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:
9
101. Install Host Library and register a client
112. Waits for a device connection
123. Prints the device's information (such as device/configuration/string descriptors)
134. Waits for the device to disconnect
145. Deregister the client and uninstall the Host Library
15
16The example demonstrates the following aspects of the USB Host Library API:
17
18- How to use the Library API to:
19 - Install and uninstall the USB Host Library
20 - Run the library event handler function a daemon task
21 - How to handle library events
22- How to use the Client API from a client task to:
23 - Register and deregister a client of the USB Host Library
24 - Run the client event handler functions
25 - How to handle client events via various callbacks
26 - Open and close a device
27 - Get a device's descriptors
28
29## How to use example
30
31### Hardware Required
32
33An 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:
34
35- GND and 5V signals of the ESP board to the GND and 5V lines of the USB port
36- GPIO 19 to D-
37- GPIO 20 to D+
38
39### Configure the project
40
41```
42idf.py menuconfig
43```
44
45* 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.
46
47### Build and Flash
48
49Build the project and flash it to the board, then run monitor tool to view serial output:
50
51```
52idf.py -p PORT flash monitor
53```
54
55(Replace PORT with the name of the serial port to use.)
56
57(To exit the serial monitor, type ``Ctrl-]``.)
58
59See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
60
61## Example Output
62
63```
64I (261) cpu_start: Starting scheduler on PRO CPU.
65I (267) DAEMON: Installing USB Host Library
66I (297) CLASS: Registering Client
67I (5067) CLASS: Opening device at address 1
68I (5067) CLASS: Getting device information
69I (5067) CLASS: Full speed
70I (5067) CLASS: bConfigurationValue 1
71I (5067) CLASS: Getting device descriptor
72*** Device descriptor ***
73bLength 18
74bDescriptorType 1
75bcdUSB 2.00
76bDeviceClass 0xef
77bDeviceSubClass 0x2
78bDeviceProtocol 0x1
79bMaxPacketSize0 64
80idVendor 0x303a
81idProduct 0x1001
82bcdDevice 1.00
83iManufacturer 1
84iProduct 2
85iSerialNumber 3
86bNumConfigurations 1
87I (5097) CLASS: Getting config descriptor
88*** Configuration descriptor ***
89bLength 9
90bDescriptorType 2
91wTotalLength 98
92bNumInterfaces 3
93bConfigurationValue 1
94iConfiguration 0
95bmAttributes 0xc0
96bMaxPower 500mA
97 *** Interface descriptor ***
98 bLength 9
99 bDescriptorType 4
100 bInterfaceNumber 0
101 bAlternateSetting 0
102 bNumEndpoints 1
103 bInterfaceClass 0x0
104 iInterface 0
105 *** Endpoint descriptor ***
106 bLength 7
107 bDescriptorType 5
108 bEndpointAddress 0x82 EP 2 IN
109 bmAttributes 0x3 INT
110 wMaxPacketSize 64
111 bInterval 1
112 *** Interface descriptor ***
113 bLength 9
114 bDescriptorType 4
115 bInterfaceNumber 1
116 bAlternateSetting 0
117 bNumEndpoints 2
118 bInterfaceClass 0x0
119 iInterface 0
120 *** Endpoint descriptor ***
121 bLength 7
122 bDescriptorType 5
123 bEndpointAddress 0x1 EP 1 OUT
124 bmAttributes 0x2 BULK
125 wMaxPacketSize 64
126 bInterval 1
127 *** Endpoint descriptor ***
128 bLength 7
129 bDescriptorType 5
130 bEndpointAddress 0x81 EP 1 IN
131 bmAttributes 0x2 BULK
132 wMaxPacketSize 64
133 bInterval 1
134 *** Interface descriptor ***
135 bLength 9
136 bDescriptorType 4
137 bInterfaceNumber 2
138 bAlternateSetting 0
139 bNumEndpoints 2
140 bInterfaceClass 0x1
141 iInterface 0
142 *** Endpoint descriptor ***
143 bLength 7
144 bDescriptorType 5
145 bEndpointAddress 0x2 EP 2 OUT
146 bmAttributes 0x2 BULK
147 wMaxPacketSize 64
148 bInterval 1
149 *** Endpoint descriptor ***
150 bLength 7
151 bDescriptorType 5
152 bEndpointAddress 0x83 EP 3 IN
153 bmAttributes 0x2 BULK
154 wMaxPacketSize 64
155 bInterval 1
156I (5227) CLASS: Getting Manufacturer string descriptor
157Espressif
158I (5237) CLASS: Getting Product string descriptor
159USB JTAG/serial debug unit
160I (5247) CLASS: Getting Serial Number string descriptor
1617C:DF:A1:E0:10:50
162```
163
164## Troubleshooting
165
166To 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.
167
168### Failing Enumeration
169
170```
171I (262) cpu_start: Starting scheduler on PRO CPU.
172I (268) DAEMON: Installing USB Host Library
173I (298) CLASS: Registering Client
174E (2748) HUB: Short string desc corrupt
175E (2748) HUB: Stage failed: CHECK_SHORT_MANU_STR_DESC
176```
177
178The log output demonstrates a device that has failed. The Hub Driver will output some error logs indicating which stage of enumeration has failed.
179
180### Blank String Descriptors
181
182The 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.
