README.rst
1.. zephyr:code-sample:: uvc
2 :name: USB Video webcam
3 :relevant-api: usbd_api usbd_uvc video_interface
4
5 Send video frames over USB.
6
7Overview
8********
9
10This sample demonstrates how to use a USB Video Class instance to send video data over USB.
11
12Upon connection, a video device will show-up on the host, usable like a regular webcam device.
13
14Any software on the host can then access the video stream as a local video source.
15
16Requirements
17************
18
19This sample uses the new USB device stack and requires the USB device
20controller ported to the :ref:`udc_api`.
21
22Building and Running
23********************
24
25If a board does not have a camera supported, the :ref:`snippet-video-sw-generator` snippet can be
26used to test without extra hardware than the USB interface, via a software-generated test pattern:
27
28.. zephyr-app-commands::
29 :zephyr-app: samples/subsys/usb/uvc
30 :board: frdm_mcxn947/mcxn947/cpu0
31 :snippets: video-sw-generator
32 :goals: build flash
33 :compact:
34
35If a board is equipped with a supported image sensor configured as the ``zephyr,camera`` chosen
36node, then it will be used as the video source. The sample can then be built as follows:
37
38.. zephyr-app-commands::
39 :zephyr-app: samples/subsys/usb/uvc
40 :board: arduino_nicla_vision/stm32h747xx/m7
41 :goals: build flash
42 :compact:
43
44The device is expected to be detected as a webcam device:
45
46.. tabs::
47
48 .. group-tab:: Ubuntu
49
50 The ``dmesg`` logs are expected to mention a ``generic UVC device``.
51
52 The ``lsusb`` is expected to show an entry for a Zephyr device.
53
54 Refers to `Ideas on board FAQ <https://www.ideasonboard.org/uvc/faq/>`_
55 for how to get more debug information.
56
57 .. group-tab:: MacOS
58
59 The ``dmesg`` logs are expected to mention a video device.
60
61 The ``ioreg -p IOUSB`` command list the USB devices including cameras.
62
63 The ``system_profiler SPCameraDataType`` command list video input devices.
64
65 .. group-tab:: Windows
66
67 The Device Manager or USBView utilities permit to list the USB devices.
68
69 The 3rd-party USB Tree View allows to review and debug the descriptors.
70
71 In addition, the `USB3CV <https://www.usb.org/document-library/usb3cv>`_ tool
72 from USB-IF can check that the device is compliant with the UVC standard.
73
74Playing the Stream
75==================
76
77The device is recognized by the system as a native webcam and can be used by any video application.
78
79For instance with VLC:
80:menuselection:`Media --> Open Capture Device --> Capture Device --> Video device name`.
81
82Or with Gstreamer and FFmpeg:
83
84.. tabs::
85
86 .. group-tab:: Ubuntu
87
88 Assuming ``/dev/video0`` is your Zephyr device.
89
90 .. code-block:: console
91
92 ffplay -i /dev/video0
93
94 .. code-block:: console
95
96 gst-launch-1.0 v4l2src device=/dev/video0 ! videoconvert ! autovideosink
97
98 .. group-tab:: MacOS
99
100 Assuming ``0:0`` is your Zephyr device.
101
102 .. code-block:: console
103
104 ffplay -f avfoundation -i 0:0
105
106 .. code-block:: console
107
108 gst-launch-1.0 avfvideosrc device-index=0 ! autovideosink
109
110 .. group-tab:: Windows
111
112 Assuming ``UVC sample`` is your Zephyr device.
113
114 .. code-block:: console
115
116 ffplay.exe -f dshow -i video="UVC sample"
117
118 .. code-block:: console
119
120 gst-launch-1.0.exe ksvideosrc device-name="UVC sample" ! videoconvert ! autovideosink
121
122The video device can also be used by web and video call applications systems.
123
124Android and iPad (but not yet iOS) are also expected to work via dedicated applications.
125
126Accessing the Video Controls
127============================
128
129On the host system, the controls would be available as video source
130control through various applications, like any webcam.
131
132.. tabs::
133
134 .. group-tab:: Ubuntu
135
136 Assuming ``/dev/video0`` is your Zephyr device.
137
138 .. code-block:: console
139
140 $ v4l2-ctl --device /dev/video0 --list-ctrls
141
142 Camera Controls
143
144 auto_exposure 0x009a0901 (menu) : min=0 max=3 default=1 value=1 (Manual Mode)
145 exposure_dynamic_framerate 0x009a0903 (bool) : default=0 value=0
146 exposure_time_absolute 0x009a0902 (int) : min=10 max=2047 step=1 default=384 value=384 flags=inactive
147
148 $ v4l2-ctl --device /dev/video0 --set-ctrl auto_exposure=1
149 $ v4l2-ctl --device /dev/video0 --set-ctrl exposure_time_absolute=1500
150
151 .. group-tab:: MacOS
152
153 The `VLC <https://www.videolan.org/vlc/>`_ client and the system Webcam Settings panel
154 allows adjustment of the supported video controls.
155
156 .. group-tab:: Windows
157
158 The `VLC <https://www.videolan.org/vlc/>`_ client and `Pot Player <https://potplayer.tv/>`_
159 client permit to further access the video controls.
160
161Software Processing
162===================
163
164Software processing tools can also use the video interface directly.
165
166Here is an example with OpenCV (``pip install opencv-python``):
167
168.. code-block:: python
169
170 import cv2
171
172 # Number of the /dev/video# interface
173 devnum = 2
174
175 cv2.namedWindow("preview")
176 vc = cv2.VideoCapture(devnum)
177
178 while (val := vc.read())[0]:
179 cv2.waitKey(20)
180 cv2.imshow("preview", val[1])
181
182 cv2.destroyWindow("preview")
183 vc.release()
184