Difference between revisions of "USB Video Class Gadget Library - libguvc"
(→UVC and 90px|baseline) |
|||
| Line 19: | Line 19: | ||
</div> | </div> | ||
| − | = UVC and | + | = UVC and libGuvc = |
Do you want to make your embedded device to look like a webcam and stream video over USB to a computer? Is yes, then you need to implement the UVC specification. | Do you want to make your embedded device to look like a webcam and stream video over USB to a computer? Is yes, then you need to implement the UVC specification. | ||
Revision as of 10:06, 13 November 2018
|
|
Template:Eval SDK Download, Demo Image download and Contact Us buttons |
Page under construction
UVC and libGuvc
Do you want to make your embedded device to look like a webcam and stream video over USB to a computer? Is yes, then you need to implement the UVC specification.
UVC or USB Video Class is a USB specification created by the USB Implementers Forum ([USB-IF]) and it is intended to standardize the video streaming functionality on the USB, that is, if you want to create a USB embedded device capable of sending video over the USB port and compatible with most operating systems and applications, then you need to implement the UVC specification.
Linux-based operating systems as well as other, have support for UVC based devices such as webcams, acting as a host for the device. In the case of the device side, also known as the gadget, the driver support is usually proprietary depending on the manufacturer. The Linux kernel has added an implementation of a [ https://github.com/torvalds/linux/blob/master/drivers/usb/gadget/function/f_uvc.c UVC gadget driver] to its mainline in order to help developers to create Linux based devices with UVC support. Beside those efforts, the current UVC driver does not implement all the UVC specification and it is quite hard to configure and use, depending heavily on a userspace application in order to complete the enumeration process and start the video streaming. For more information on how to configure and use the UVC driver got to How to use the UVC gadget driver in Linux.
The USB Video Class Gadget Library or 
for short is a platform agnostic library that simplifies the development of UVC based gadget devices by encapsulating the most of the UVC communication leaving just the basic setup to the user. It runs on top of the UVC function driver in the user space and takes care of the communication between the user application and the linux driver stack. The figure 1 depicts the software stack on a common use case scenario.
libguvc in action
Features
The following table list the main features provided by the libguvc and the corresponding library version:
| Feature | Release version |
|---|---|
| User Pointer support | 1.0.x |
| Extension Units support | 1.0.x |
| YUY2 video format support | 1.0.x |
| USB requests support | 1.0.x |
| Pull mode support | 1.0.x |
| MMAP support | 1.1.x |
| MJPEG support | 1.1.x |
| gst-uvc-sink element | 1.2.x |
| H264 support* | 1.3.x |
- The libguvc library only implements the UVC 1.1 specification since the linux kernel driver only implements UVC 1.1. Future support for UVC 1.5 can be added after the Linux kernel driver adds the support.
Platform agnostic
The libguvc library can be integrated on any embedded device and it is independent of the SoC architecture and kernel version. It only requires UVC gadget driver to be enabled in the platform.
Note: libguvc uses the kernel's UVC gadget driver as is; the patches provided are intended to demonstrate how to add support for features such as H264 and MJPEG, they are not intended to fix any issues (if any) on the UVC driver or the platform's USB stack.
Independent of the host OS
The libguvc uses the Linux UVC gadget driver and implements the UVC standard so that the gadget device using the library can be used on any OS that supports the UVC standard such as Linux, Windows* and Mac OS X. Likewise it can be used by any standard capture application such as Skype, VLC, guvcview, among others.
* For Windows it is required to create a custom Windows INF file in order for the device to be successfully registered on the system
Independent of user application implementation
The libguvc library can be integrated with any user application and only requires to be feed with video frames that will be send to the USB endpoint. Its design allows to easily integrate the library with any video frame wrappers such as V4L2 buffers or GStreamer buffers, among others; taking care only of the real video content and allowing the user to specify the memory management for the buffer types used.
As an example of its flexibility the library comes with sample code using different implementation methods such as specific V4L2 application and GStreamer based application. The sample code can be found at $(LIBGUVC_DIR)/src/test directory.
GStreamer integration
On release 1.2.x the library includes a GStreamer element that can be used to send UVC driver data directly to a host computer on a simple GStreamer pipeline speeding up the development time for a UVC based application.
User Pointer and MMAP support
libguvc can be used on User Pointer or MMAP mode in order to increase the compatibility with the user space applications.
Extension Units support
As part of the key features on the libguvc there is the support for UVC Extension Units (XU) allowing the user to implement custom controls in order to meet specific design requirements with a minimum of effort.
USB requests support
libguvc allows the installation of callback functions on the user application in order to receive any USB request on the controls exposed, this provides a direct communication between the host computer and the user application.
Video formats support
On version 1.0.x the libguvc provides support for YUY2 video format only. Releases 1.1.x and 1.3.x provide support for MJPEG and H264 video formats as well.
How does it work?
To use libguvc is really simply, the API is widely explained in the Doxygen documentation at $(LIBGUVC_DIR)/src/docs/.
A simple pseudo code that depicts the basic API sequence is shown below. libguvc API allows the user to interact with the UVC driver using just a set of methods and callbacks, abstracting all the complexity of driver interaction and configuration.
#include <libguvc.h>
uvc_device * device;
void release_buffer (void **entity, void *args)
{
/* Release the buffer data that has been sent through the UVC */
}
void fill_uvc_buffer (unsigned long *data_addr, int *data_size, int *bytes_used, void **entity, void *args)
{
/* send the video data and custom information to the library */
}
int main (int argc , char **argv)
{
...
uvc_init (device, "/dev/video0");
...
/* Set the callbacks to pass and release the video content */
uvc_set_pull_data_handler (device, fill_uvc_buffer, NULL);
uvc_set_release_data_handler (device, release_buffer, NULL);
...
uvc_start (device);
...
uvc_close (device);
return 0;
}
Additionally the API provides support for a wide range of configurable settings to use specific features such as Extension Units or UVC controls requests.
Demo Images
FAQ: What is the difference between a trial version and the full? Both versions are fully functional, the trial version is fixed to a few set of pre-defined video resolutions and runs only for about 5min before it disconnects the UVC session automatically.
You can download the following demo sd card images in order to test a trial version of the library.
Contact Us
If you are interested in purchasing the USB Video Class Gadget Library, or would like more information please send an email to support@ridgerun.com.
Since the libguvc is platform agnostic, you can also request for a custom demo image for any other platform by posting your Inquiry at our Contact Us Link directly...
