Skip to content

Commit 206fe63

Browse files
tore-espressiftore-espressif
committed
Merge branch 'feat/new_usb_uvc_example' into 'master'
refactor(usb/host): Update UVC example for new UVC driver v2.0 Closes IDF-10240 See merge request espressif/esp-idf!38359
2 parents 8e25a37 + 02a5561 commit 206fe63

File tree

15 files changed

+240
-838
lines changed

15 files changed

+240
-838
lines changed

‎docs/en/api-reference/peripherals/usb_host.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -403,7 +403,7 @@ UVC
403403
"""
404404

405405
* A host class driver for the USB Video Device Class is distributed as a managed component via the `ESP Component Registry <https://components.espressif.com/component/espressif/usb_host_uvc>`__.
406-
* :example:`peripherals/usb/host/uvc` demonstrates how to capture video from a USB camera using the `libuvc` library and stream the video over Wi-Fi by hosting a TCP server, with the option to visualize the captured video on a PC using the provided `player.py` script.
406+
* :example:`peripherals/usb/host/uvc` demonstrates how to capture video frames from a USB camera using the UVC driver.
407407

408408
.. ---------------------------------------------- USB Host Menuconfig --------------------------------------------------
409409

‎docs/zh_CN/api-reference/peripherals/usb_host.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -403,7 +403,7 @@ UVC
403403
"""
404404

405405
* USB 视频设备 Class 的主机 Class 驱动程序作为托管组件通过 `乐鑫组件注册表 <https://components.espressif.com/component/espressif/usb_host_uvc>`__ 分发。
406-
* 示例 :example:`peripherals/usb/host/uvc` 演示了如何使用 `libuvc` 库从 USB 摄像头捕获视频，并通过托管 TCP 服务器将视频流通过 Wi-Fi 传输，同时提供了使用 ``player.py`` 脚本在 PC 上查看捕获视频的选项。
406+
* 示例 :example:`peripherals/usb/host/uvc` 演示了如何使用 UVC 驱动程序从 USB 摄像头捕获视频帧。
407407

408408
.. ---------------------------------------------- USB Host Menuconfig --------------------------------------------------
409409

‎examples/peripherals/usb/host/uvc/README.md‎

Lines changed: 43 additions & 161 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,9 @@
55

66
## Overview
77

8-
This example demonstrates how to:
8+
This example shows basic usage of [USB UVC host driver](https://components.espressif.com/components/espressif/usb_host_uvc). The example waits for USB camera connection, it then configures the camera and starts streaming video frames until the device is removed.
99

10-
- Capture video from a USB camera using the `libuvc` library.
11-
- Stream the video over WiFi by hosting a TCP server.
12-
13-
The example enumerates a connected USB camera, negotiates a selected resolution along with an associated `FPS`, then starts capturing video. The `frame_callback` function is then invoked after receiving each frame. Users can process the received frames according to their needs.
14-
15-
Optionally, the captured video can be visualized on a PC with help of the `player.py` script provided in this example. After setting the `Example Configuration->Enable streaming` option in menuconfig, the example will create a TCP server upon startup, and waits until `player.py` connects to the server. Once a connection is established, the example streams each received frame to the PC for visualization. The network connection can be configured in menuconfig via `Example Connection Configuration`.
16-
17-
**Notice** that `libuvc` selects highest possible `dwMaxPayloadTransferSize` by default. As a result, this example will manually overwrite this value to 512 bytes (the maximum packet size supported by ESP32-S2/S3).
10+
More advanced examples can be found in [UVC host driver repository](https://github.com/espressif/esp-usb/tree/master/host/class/uvc/usb_host_uvc/examples).
1811

1912
(See the README.md file in the upper level 'examples' directory for more information about examples.)
2013

@@ -26,52 +19,18 @@ Optionally, the captured video can be visualized on a PC with help of the `playe
2619
* Exposed USB host connector
2720
* USB camera
2821

29-
Running this example on an **ESP module without external PSRAM will fail on initialization**. Please select your PSRAM configuration in menuconfig `Component config->ESP PSRAM`. If you manually disable PSRAM, the required framebuffers might not fit into DRAM (especially on ESP32-S2).
22+
Running this example on an **ESP module without external PSRAM will fail on initialization**. Please select your PSRAM configuration in menuconfig `Component config->ESP PSRAM`. If you manually disable PSRAM, the required frame buffers might not fit into DRAM (especially on ESP32-S2). If you absolutely must not use PSRAM, consider the following for minimizing RAM usage:
23+
* Select smaller resolution (eg. 320x240)
24+
* Select fewer frame buffers (eg. 2)
25+
* Select smaller and fewer URBs (eg. 2x 2kB)
3026

3127
Follow instructions in [examples/usb/README.md](../../README.md) for specific hardware setup.
3228

33-
### Configure the project
34-
35-
Following configuration is needed for streaming video:
36-
37-
Open the project configuration menu (`idf.py menuconfig`).
38-
39-
In the `Example Connection Configuration` menu:
40-
41-
* Set the Wi-Fi configuration.
42-
* Set `WiFi SSID`.
43-
* Set `WiFi Password`.
29+
### Frame format
4430

45-
In the `Example Configuration` menu:
46-
47-
* Set the Example configuration
48-
* `Enable streaming`
49-
50-
* Select one of UVC Protocol Mode
51-
* `Auto`
52-
* `Custom`
53-
54-
Optional: If you need, change the other options according to your requirements.
55-
56-
Additionally, the `player.py` python script makes use of the `opencv-python` and `numpy` packages which are not included in the `idf-env` environment by default. Run following command to install those packages:
57-
58-
```bash
59-
pip install opencv-python numpy
60-
```
31+
You can select frame format in [main.c](./main/main.c) file in `stream_config` variable. Default is set to very common 640x480@15FPS, MJPEG encoded.
6132

62-
#### UVC Protocol Mode: Auto
63-
64-
When the protocol mode is set to Auto, the example will make three attempts to negotiate the protocol with following parameters:
65-
66-
1. Attempt: 640x480, 15 FPS, MJPEG
67-
2. Attempt: 320x240, 30 FPS, MJPEG
68-
3. Attempt: 320x240, first available FPS, MJPEG
69-
70-
If all three attempts result in an error, the example displays the error message and suggests to try another USB UVC Device.
71-
72-
#### UVC Protocol Mode: Custom
73-
74-
When the protocol mode set to Custom, the example tries to negotiate the protocol using user provided values for the following parameters: Attempts, Width, Height, FPS, and Frame Coding format. After all attempts result in an error, the example displays the error message and suggests to try another USB UVC device.
33+
This example will print supported formats on device connection - this can be disabled in menuconfig ` Component config → USB HOST UVC`. The frame format can also be changed in runtime by calling `uvc_host_stream_format_select()` function.
7534

7635
### Build and Flash
7736

@@ -87,128 +46,51 @@ See the Getting Started Guide for all the steps to configure and use the ESP-IDF
8746

8847
## Known limitations
8948

90-
Having only a Full Speed USB peripheral and hardware limited MPS (maximum packet size) to 512 bytes, the ESP32-S2/S3 is capable of reading data at approximately 0.5 MB/s. When connected to Full Speed USB host, cameras normally provide resolution no larger than 640x480 pixels. The following two formats are the most commonly supported at Full Speed (both encoded in MJPEG):
91-
* 320x240 30 FPS
92-
* 640x480 15 FPS
49+
On targets with Full Speed USB peripheral the MPS (maximum packet size) is limited to 512 bytes, the ESP32-S2/S3 is capable of reading data at approximately 0.5 MB/s. When connected to Full Speed USB host, cameras usually provide resolution no larger than 640x480 pixels. The following two formats are the most commonly supported at Full Speed :
50+
* 320x240 30 FPS MJPEG
51+
* 640x480 15 FPS MJPEG
9352

9453
## Tested cameras
9554
* Logitech C980
9655
* Logitech C270
56+
* Logitech C170
57+
* Logitech Brio 100
9758
* CANYON CNE-CWC2
59+
* Trust WebCam
60+
* Anker Powerconf C200
61+
* Microsoft LifeCam HD-6000
62+
* Asus Webcam C3
9863

9964
## Example Output
10065

66+
Output with USB camera already connected at program start:
10167
```
10268
...
103-
I (1186) example: Waiting for USB UVC device connection ...
104-
I (1606) example: Device found
105-
DEVICE CONFIGURATION (0c45:6340/ S) ---
106-
Status: idle
107-
VideoControl:
108-
bcdUVC: 0x0100
109-
VideoStreaming(1):
110-
bEndpointAddress: 129
111-
Formats:
112-
MJPEGFormat(1)
113-
bits per pixel: 0
114-
GUID: 4d4a5047000000000000000000000000 (MJPG)
115-
default frame: 1
116-
aspect ratio: 0x0
117-
interlace flags: 00
118-
copy protect: 00
119-
FrameDescriptor(1)
120-
capabilities: 00
121-
size: 640x480
122-
bit rate: 24576000-147456000
123-
max frame size: 614400
124-
default interval: 1/30
125-
interval[0]: 1/30
126-
interval[1]: 1/25
127-
interval[2]: 1/20
128-
interval[3]: 1/15
129-
interval[4]: 1/10
130-
interval[5]: 1/5
131-
FrameDescriptor(2)
132-
capabilities: 00
133-
size: 352x288
134-
bit rate: 8110080-48660480
135-
max frame size: 202752
136-
default interval: 1/30
137-
interval[0]: 1/30
138-
interval[1]: 1/25
139-
interval[2]: 1/20
140-
interval[3]: 1/15
141-
interval[4]: 1/10
142-
interval[5]: 1/5
143-
FrameDescriptor(3)
144-
capabilities: 00
145-
size: 320x240
146-
bit rate: 6144000-36864000
147-
max frame size: 153600
148-
default interval: 1/30
149-
interval[0]: 1/30
150-
interval[1]: 1/25
151-
interval[2]: 1/20
152-
interval[3]: 1/15
153-
interval[4]: 1/10
154-
interval[5]: 1/5
155-
FrameDescriptor(4)
156-
capabilities: 00
157-
size: 176x144
158-
bit rate: 2027520-12165120
159-
max frame size: 50688
160-
default interval: 1/30
161-
interval[0]: 1/30
162-
interval[1]: 1/25
163-
interval[2]: 1/20
164-
interval[3]: 1/15
165-
interval[4]: 1/10
166-
interval[5]: 1/5
167-
FrameDescriptor(5)
168-
capabilities: 00
169-
size: 160x120
170-
bit rate: 1536000-9216000
171-
max frame size: 38400
172-
default interval: 1/30
173-
interval[0]: 1/30
174-
interval[1]: 1/25
175-
interval[2]: 1/20
176-
interval[3]: 1/15
177-
interval[4]: 1/10
178-
interval[5]: 1/5
179-
StillFrameDescriptor
180-
bEndPointAddress: 00
181-
wWidth(1) = 640
182-
wHeight(1) = 480
183-
wWidth(2) = 352
184-
wHeight(2) = 288
185-
wWidth(3) = 320
186-
wHeight(3) = 240
187-
wWidth(4) = 176
188-
wHeight(4) = 144
189-
wWidth(5) = 160
190-
wHeight(5) = 120
191-
END DEVICE CONFIGURATION
192-
I (1796) example: Negotiate streaming profile 640x480, fps 15 ...
193-
I (1816) example: Negotiation complete.
194-
bmHint: 0001
195-
bFormatIndex: 1
196-
bFrameIndex: 1
197-
dwFrameInterval: 666666
198-
wKeyFrameRate: 0
199-
wPFrameRate: 0
200-
wCompQuality: 0
201-
wCompWindowSize: 0
202-
wDelay: 23469
203-
dwMaxVideoFrameSize: 614400
204-
dwMaxPayloadTransferSize: 512
205-
bInterfaceNumber: 1
206-
I (1836) example: Streaming...
207-
I (4016) example: fps: 10, bytes per second: 69920
69+
I (1460) main_task: Calling app_main()
70+
I (1460) UVC example: Installing USB Host
71+
I (1500) UVC example: Installing UVC driver
72+
I (1500) UVC example: Opening UVC device 0x0000:0x0000 [email protected]...
73+
I (1500) main_task: Returned from app_main()
74+
*** Configuration descriptor ***
75+
76+
...
77+
Here is rest of Configuration descriptor
78+
...
79+
80+
I (3140) UVC example: UVC Device OPENED!
81+
I (3240) UVC example: Stream start. Iteration 0
82+
I (4410) UVC example: New frame! Len: 13392
83+
I (4470) UVC example: New frame! Len: 13392
84+
I (4530) UVC example: New frame! Len: 13392
20885
20986
...
87+
More frames received
88+
...
89+
90+
I (8310) UVC example: New frame! Len: 18512
91+
I (8310) UVC example: Stream stop
92+
I (10440) UVC example: Stream start. Iteration 1
21093
211-
I (44916) example: fps: 9, bytes per second: 62928
212-
E (45626) USBH: Device 1 gone
213-
I (45636) example: Done streaming.
94+
...
95+
Streaming continues here
21496
```

‎examples/peripherals/usb/host/uvc/main/CMakeLists.txt‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,5 @@
1-
idf_component_register(SRCS "main.c" "tcp_server.c"
2-
INCLUDE_DIRS ""
1+
idf_component_register(SRCS "main.c"
32
PRIV_REQUIRES
4-
nvs_flash
53
usb
6-
esp_ringbuf
74
esp_psram # Required for CONFIG_SPIRAM
8-
esp_timer
9-
esp_wifi
10-
esp_driver_gpio
115
)

‎examples/peripherals/usb/host/uvc/main/Kconfig.projbuild‎

Lines changed: 0 additions & 106 deletions
This file was deleted.

‎examples/peripherals/usb/host/uvc/main/idf_component.yml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
11
## IDF Component Manager Manifest File
22
dependencies:
33
idf: ">=5.0"
4-
usb_host_uvc: "^1.0.3"
5-
mdns: "^1.2.5"
6-
protocol_examples_common:
7-
path: ${IDF_PATH}/examples/common_components/protocol_examples_common
4+
usb_host_uvc: "^2.2.0"

0 commit comments

Comments
 (0)