Difference between revisions of "USB Video Class Gadget Library - libguvc"

From RidgeRun Developer Connection
Jump to: navigation, search
(→‎libGuvc in action)
m
 
(33 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
<seo title="USB Video Class Gadget Library | UVC Driver Linux | UVC Linux" titlemode="replace" keywords=" GStreamer, WebRTC, Embedded Linux, Nvidia, Xilinx, TI, NXP, Freescale, Linux Software development, Embedded Linux SDK, Embedded Linux Application development, GStreamer Multimedia Framework, Gstreamer Plugin,Streaming, Protocol, Server, WebRTC, Media, Payloader, Encoder,UVC,USB Video Class,UVC gadget driver,USB Video Class Gadget Library,libGuvc,UVC gadget driver,UVC Function Driver"  description="Simplify the development of UVC based gadget devices with the USB Video Class Gadget Library or libguvc. Learn about UVC Driver device systems now at RidgeRun."></seo>
+
<seo title="USB Video Class Gadget Library | UVC Driver Linux | UVC Linux" titlemode="replace" keywords=" GStreamer, WebRTC, Embedded Linux, NVIDIA, Xilinx, TI, NXP, Freescale, Linux Software development, Embedded Linux SDK, Embedded Linux Application development, GStreamer Multimedia Framework, Gstreamer Plugin, Streaming, Protocol, Server, WebRTC, Media, Payloader, Encoder, UVC, USB Video Class, UVC gadget driver, USB Video Class Gadget Library, libGuvc, UVC gadget driver, UVC Function Driver, USB webcam, USB specification, NXP i.MX8M Mini, NXP, i.MX8M, i.MX8M Mini,"  description="Simplify the development of UVC based gadget devices with the USB Video Class Gadget Library or libguvc. Learn about UVC Driver device systems now at RidgeRun."></seo>
  
 
<table>
 
<table>
Line 6: Line 6:
 
<td>
 
<td>
 
<html>
 
<html>
−
<div class="ecwid ecwid-SingleProduct-v2 ecwid-SingleProduct-v2-bordered ecwid-SingleProduct-v2-centered ecwid-Product ecwid-Product-65237550" itemscope itemtype="http://schema.org/Product" data-single-product-id="65237550"><div itemprop="image"></div><div class="ecwid-title" itemprop="name"></div><div itemtype="http://schema.org/Offer" itemscope itemprop="offers"><div class="ecwid-productBrowser-price ecwid-price" itemprop="price" data-spw-price-location="button"><div itemprop="priceCurrency" content="USD"></div></div></div><div customprop="options"></div><div customprop="addtobag"></div></div><script type="text/javascript" src="https://app.ecwid.com/script.js?7804024&data_platform=singleproduct_v2" charset="utf-8"></script><script type="text/javascript">xProduct()</script>
+
<div id='product-component-0a0eeadc52c'></div>
 +
    <script type="text/javascript">
 +
    /*<![CDATA[*/
 +
 
 +
    (function () {
 +
      var scriptURL = 'https://sdks.shopifycdn.com/buy-button/latest/buy-button-storefront.min.js';
 +
      if (window.ShopifyBuy) {
 +
        if (window.ShopifyBuy.UI) {
 +
          ShopifyBuyInit();
 +
        } else {
 +
          loadScript();
 +
        }
 +
      } else {
 +
        loadScript();
 +
      }
 +
 
 +
      function loadScript() {
 +
        var script = document.createElement('script');
 +
        script.async = true;
 +
        script.src = scriptURL;
 +
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(script);
 +
        script.onload = ShopifyBuyInit;
 +
      }
 +
 
 +
      function ShopifyBuyInit() {
 +
        var client = ShopifyBuy.buildClient({
 +
          domain: 'ridgerun1.myshopify.com',
 +
          storefrontAccessToken: 'b0ca98633a82de5d2f63cd51f5af30ac',
 +
        });
 +
 
 +
        ShopifyBuy.UI.onReady(client).then(function (ui) {
 +
          ui.createComponent('product', {
 +
            id: [1684663173191],
 +
            node: document.getElementById('product-component-0a0eeadc52c'),
 +
            moneyFormat: '%24%7B%7Bamount%7D%7D',
 +
            options: {
 +
  "product": {
 +
    "variantId": "all",
 +
    "width": "240px",
 +
    "contents": {
 +
      "imgWithCarousel": false,
 +
      "variantTitle": false,
 +
      "description": false,
 +
      "buttonWithQuantity": false,
 +
      "quantity": false
 +
    },
 +
    "text": {
 +
      "button": "BUY NOW"
 +
    },
 +
    "styles": {
 +
      "product": {
 +
        "@media (min-width: 601px)": {
 +
          "max-width": "100%",
 +
          "margin-left": "0",
 +
          "margin-bottom": "50px"
 +
        }
 +
      },
 +
      "button": {
 +
        "background-color": "#007493",
 +
        "font-size": "18px",
 +
        "padding-top": "17px",
 +
        "padding-bottom": "17px",
 +
        ":hover": {
 +
          "background-color": "#006884"
 +
        },
 +
        ":focus": {
 +
          "background-color": "#006884"
 +
        }
 +
      },
 +
      "quantityInput": {
 +
        "font-size": "18px",
 +
        "padding-top": "17px",
 +
        "padding-bottom": "17px"
 +
      },
 +
      "compareAt": {
 +
        "font-size": "12px"
 +
      }
 +
    }
 +
  },
 +
  "cart": {
 +
    "contents": {
 +
      "button": true
 +
    },
 +
    "styles": {
 +
      "button": {
 +
        "background-color": "#007493",
 +
        "font-size": "18px",
 +
        "padding-top": "17px",
 +
        "padding-bottom": "17px",
 +
        ":hover": {
 +
          "background-color": "#006884"
 +
        },
 +
        ":focus": {
 +
          "background-color": "#006884"
 +
        }
 +
      },
 +
      "footer": {
 +
        "background-color": "#ffffff"
 +
      }
 +
    }
 +
  },
 +
  "modalProduct": {
 +
    "contents": {
 +
      "img": false,
 +
      "imgWithCarousel": true,
 +
      "variantTitle": false,
 +
      "buttonWithQuantity": true,
 +
      "button": false,
 +
      "quantity": false
 +
    },
 +
    "styles": {
 +
      "product": {
 +
        "@media (min-width: 601px)": {
 +
          "max-width": "100%",
 +
          "margin-left": "0px",
 +
          "margin-bottom": "0px"
 +
        }
 +
      },
 +
      "button": {
 +
        "background-color": "#007493",
 +
        "font-size": "18px",
 +
        "padding-top": "17px",
 +
        "padding-bottom": "17px",
 +
        ":hover": {
 +
          "background-color": "#006884"
 +
        },
 +
        ":focus": {
 +
          "background-color": "#006884"
 +
        }
 +
      },
 +
      "quantityInput": {
 +
        "font-size": "18px",
 +
        "padding-top": "17px",
 +
        "padding-bottom": "17px"
 +
      }
 +
    }
 +
  },
 +
  "toggle": {
 +
    "styles": {
 +
      "toggle": {
 +
        "background-color": "#007493",
 +
        ":hover": {
 +
          "background-color": "#006884"
 +
        },
 +
        ":focus": {
 +
          "background-color": "#006884"
 +
        }
 +
      },
 +
      "count": {
 +
        "font-size": "18px"
 +
      }
 +
    }
 +
  },
 +
  "productSet": {
 +
    "styles": {
 +
      "products": {
 +
        "@media (min-width: 601px)": {
 +
          "margin-left": "-20px"
 +
        }
 +
      }
 +
    }
 +
  }
 +
}
 +
          });
 +
        });
 +
      }
 +
    })();
 +
    /*]]>*/
 +
    </script>
 
</html>
 
</html>
 
</td>
 
</td>
 
<td><center>
 
<td><center>
−
{{Template:Eval SDK Download, Demo Image download and Contact Us buttons}}
+
{{Sponsor Button}}
 +
{{ContactUs Button}}
 
</center></td></tr></table>
 
</center></td></tr></table>
  
−
<pre style="color: red"> Page under construction </pre>
+
<br>
  
 
<div class="center">
 
<div class="center">
Line 19: Line 188:
 
</div>
 
</div>
  
−
= UVC and libGuvc =
+
== UVC and libGuvc ==
  
 
Do you want to make your embedded device to look like a webcam and stream video over USB to a computer? If 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? If yes, then you need to implement the UVC specification.  
Line 32: Line 201:
 
[[File:Libguvc.png|600px|thumb|center|Figure 1. Software stack description using libguvc]]
 
[[File:Libguvc.png|600px|thumb|center|Figure 1. Software stack description using libguvc]]
  
−
= Features =
+
== Features ==
  
 
The following table list the main features provided by the ''libguvc'' and the corresponding library version:  
 
The following table list the main features provided by the ''libguvc'' and the corresponding library version:  
Line 40: Line 209:
 
! Feature
 
! Feature
 
! style="text-align:center;" | Release version
 
! style="text-align:center;" | Release version
 +
|-
 +
| Isochronous endpoint support
 +
| style="text-align:center;" | 1.0.x
 
|-
 
|-
 
| User Pointer support
 
| User Pointer support
Line 74: Line 246:
 
* 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.  
 
* 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 ==
+
=== 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.
 
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.
+
For the time being, we have tested the library in the following platforms:
  
−
== Independent of the host OS ==
+
 
 +
{| class="wikitable" style="text-align: center; margin: auto;"
 +
!colspan="6"|Tested Environments
 +
|-
 +
| '''SoC'''
 +
| '''Kernel Version'''
 +
|-
 +
| NXP i.MX6
 +
| 3.14
 +
|-
 +
| NXP I.MX8MM
 +
| 4.14 / 5.4
 +
|-
 +
| NXP I.MX8MQ
 +
| 5.15
 +
|-
 +
| NVIDIA Jetson
 +
| 4.9 / 5.x
 +
|-
 +
| Qualcomm Snapdragon 410
 +
| 4.14
 +
|}
 +
 
 +
If you are interested in testing it on a different platform please [https://www.ridgerun.com/contact Contact Us].
 +
 
 +
'''Note: ''' libGuvc uses the kernel's UVC gadget driver as is; to demonstrate how to add support for features such as H264 or XU, kernel patches are needed and Ridgerun has experience creating them, 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 most operating systems that supports the UVC standard such as Linux, Windows* and Mac OS X. Likewise it can be used by most standard capture application such as Skype, VLC, guvcview, among others.  
 
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 most operating systems that supports the UVC standard such as Linux, Windows* and Mac OS X. Likewise it can be used by most standard capture application such as Skype, VLC, guvcview, among others.  
Line 86: Line 285:
 
'''*''' ''For Windows it is required to create a custom Windows INF file in order for the device to be successfully registered on the system''
 
'''*''' ''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 ==
+
=== 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 sent 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.  
 
The ''libGuvc'' library can be integrated with any user application and only requires to be feed with video frames that will be sent 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.  
  
−
== GStreamer integration ==
+
=== GStreamer integration ===
  
 
On release 1.2.x the library includes a sample 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. You can use this element as a starting point for your own Gstreamer elements and add additional features.
 
On release 1.2.x the library includes a sample 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. You can use this element as a starting point for your own Gstreamer elements and add additional features.
  
−
== User Pointer and MMAP support ==
+
=== User Pointer and MMAP support ===
  
 
''libGuvc'' can be used on User Pointer or MMAP mode in order to increase the compatibility with the userspace applications.
 
''libGuvc'' can be used on User Pointer or MMAP mode in order to increase the compatibility with the userspace applications.
  
−
== Extension Units support ==
+
=== 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.
 
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 ==
+
=== 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.
 
''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 ==
+
=== 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.
 
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.
  
−
== USB 2.0 / USB 3.0 support ==
+
=== USB 2.0 / USB 3.0 support ===
  
 
Since ''libGuvc'' works on top of the Linux UVC driver, it can work on USB 2.0 and USB 3.0 interfaces as long as its support is provided for the USB driver stack in the target platform.
 
Since ''libGuvc'' works on top of the Linux UVC driver, it can work on USB 2.0 and USB 3.0 interfaces as long as its support is provided for the USB driver stack in the target platform.
  
−
= How does it work? =
+
== How does it work? ==
  
−
''libGuvc'' is distributed as an automake project that generates a library that can be externally used for another application in order to add UVC streaming capabilities. Since ''libGuvc'' uses the UVC kernel driver, it uses the [https://linuxtv.org/downloads/v4l-dvb-apis/kapi/v4l2-event.html V4L2 events] interface to communicate. Each event is mapped to specific callbacks and methods within the library and the user application in order to ensure the intercommunication.  
+
''libGuvc'' is distributed as an automake project that generates a library that can be externally used for another application in order to add UVC streaming capabilities. Since ''libGuvc'' uses the UVC kernel driver, it uses the [https://linuxtv.org/downloads/v4l-dvb-apis/driver-api/v4l2-event.html V4L2 events] interface to communicate. Each event is mapped to specific callbacks and methods within the library and the user application in order to ensure the intercommunication.  
  
 
'''libGuvc'' API is quite simple, the following pseudo code depicts the basic sequence used on a typical user application. ''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.
 
'''libGuvc'' API is quite simple, the following pseudo code depicts the basic sequence used on a typical user application. ''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.
  
−
<pre>
+
<syntaxhighlight lang=C>
 
#include <libguvc.h>
 
#include <libguvc.h>
−
 
  
 
uvc_device * device;
 
uvc_device * device;
Line 159: Line 357:
  
 
}
 
}
−
</pre>
+
</syntaxhighlight>
  
 
Additionally, the API provides support for a wide range of configurable settings to use specific features such as Extension Units or UVC controls requests.
 
Additionally, the API provides support for a wide range of configurable settings to use specific features such as Extension Units or UVC controls requests.
  
−
= Can I use libGuvc with another gadget driver? =
+
== Can I use libGuvc with another gadget driver? ==
  
 
Since ''libGuvc'' uses the standard Linux driver for UVC, it works like any other USB gadget driver in the system. This means that you can set it up as a composite driver in order to get UVC function working alongside with other gadget functions such as UAC (audio over USB), mass storage, RNDIS, etc. For more information about USB gadget, composite drivers see [[USB gadget composite drivers]].
 
Since ''libGuvc'' uses the standard Linux driver for UVC, it works like any other USB gadget driver in the system. This means that you can set it up as a composite driver in order to get UVC function working alongside with other gadget functions such as UAC (audio over USB), mass storage, RNDIS, etc. For more information about USB gadget, composite drivers see [[USB gadget composite drivers]].
Line 172: Line 370:
 
[[File:libguvc_composite_diagram.png|500px|thumb|center|Figure 2. UVC composite driver example]]
 
[[File:libguvc_composite_diagram.png|500px|thumb|center|Figure 2. UVC composite driver example]]
  
−
= Demo Images =
+
== Dependencies ==
  
−
'''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.''
+
LibGUVC needs the next dependencies to be fulfilled:
 +
 +
<syntaxhighlight lang='bash'>
 +
sudo apt install -y automake
 +
sudo apt install -y build-essential
 +
</syntaxhighlight>
  
−
You can download the following demo sd card images in order to test a trial version of the library.
+
If you want to use LibGUVC with GStreamer then fulfilled the next dependencies:
  
−
* [http://downloads.ridgerun.com/demos/libguvc-demos/imx6-sabrelite-libguvc_demo_ov5640.tar.gz i.MX6 Sabre Lite with OV5640 demo image] ([http://downloads.ridgerun.com/demos/libguvc-demos/imx6-sabrelite-libguvc_demo_ov5640.sha1 sha1sum])
+
 +
<syntaxhighlight lang='bash'>
 +
sudo apt install \
 +
gstreamer1.0-x \
 +
libgstreamer1.0-dev \
 +
libgstreamer-plugins-base1.0-dev \
 +
gstreamer1.0-plugins-bad \
 +
libgstreamer-plugins-bad1.0-dev \
 +
gstreamer1.0-nice \
 +
gstreamer1.0-plugins-ugly
 +
</syntaxhighlight>
  
−
* [http://downloads.ridgerun.com/demos/libguvc-demos/imx6-sabrelite-libguvc_demo_video_pattern.tar.gz i.MX6 Sabre Lite without camera sensor demo image] ([http://downloads.ridgerun.com/demos/libguvc-demos/imx6-sabrelite-libguvc_demo_video_pattern.sha1 sha1sum])
 
  
−
= libGuvc in action =
+
== Demo Images ==
  
−
== Running libGuvc in NVidia Xavier ==
+
'''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 sets of pre-defined video resolutions and runs only for about 5min before it disconnects the UVC session automatically.''
 +
 
 +
If you are interested in testing the library please [https://www.ridgerun.com/contact Contact Us]
 +
 
 +
== libGuvc in action ==
 +
 
 +
=== Running libGuvc in NVIDIA Jetson AGX Xavier ===
  
 
<div class="center">
 
<div class="center">
Line 190: Line 408:
 
</div>
 
</div>
  
−
== Running libGuvc in i.MX6 ==
+
=== Running libGuvc in i.MX6 ===
  
 
<div class="center">
 
<div class="center">
Line 196: Line 414:
 
</div>
 
</div>
  
−
= Contact Us =
+
{{ContactUs}}
−
 
 
−
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'''. <br>
 
−
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 [http://www.ridgerun.com/contact '''Contact Us Link'''] directly.
 
  
−
[[Category:USB]].
+
[[Category:USB]][[Category:IMX6]] [[Category:IMX6 Demo]][[Category:Jetson]][[Category:JetsonNano]][[Category: JetsonTX2‏‎]][[Category:NVIDIA Xavier]]
−
[[Category:SdkAddOn]]
 
−
[[Category:IMX6]].
 
−
[[Category:IMX6 Demo]]
 

Latest revision as of 09:29, 28 April 2023

Error creating thumbnail: Unable to save thumbnail to destination

RR Contact Us.png


UVC and libGuvc

Do you want to make your embedded device to look like a webcam and stream video over USB to a computer? If 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 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 Libguvc-logo-plain.png 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 standard UVC driver in the Linux kernel and exposes a friendly interface for the userspace application, taking care of the communication between the user application and the Linux driver stack. Figure 1 depicts the software stack on a common use case scenario.

Figure 1. Software stack description using libguvc

Features

The following table list the main features provided by the libguvc and the corresponding library version:

Feature Release version
Isochronous endpoint support 1.0.x
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
Bulk endpoint support 1.4.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.

For the time being, we have tested the library in the following platforms:


Tested Environments
SoC Kernel Version
NXP i.MX6 3.14
NXP I.MX8MM 4.14 / 5.4
NXP I.MX8MQ 5.15
NVIDIA Jetson 4.9 / 5.x
Qualcomm Snapdragon 410 4.14

If you are interested in testing it on a different platform please Contact Us.

Note: libGuvc uses the kernel's UVC gadget driver as is; to demonstrate how to add support for features such as H264 or XU, kernel patches are needed and Ridgerun has experience creating them, 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 most operating systems that supports the UVC standard such as Linux, Windows* and Mac OS X. Likewise it can be used by most 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 sent 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.

GStreamer integration

On release 1.2.x the library includes a sample 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. You can use this element as a starting point for your own Gstreamer elements and add additional features.

User Pointer and MMAP support

libGuvc can be used on User Pointer or MMAP mode in order to increase the compatibility with the userspace 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.

USB 2.0 / USB 3.0 support

Since libGuvc works on top of the Linux UVC driver, it can work on USB 2.0 and USB 3.0 interfaces as long as its support is provided for the USB driver stack in the target platform.

How does it work?

libGuvc is distributed as an automake project that generates a library that can be externally used for another application in order to add UVC streaming capabilities. Since libGuvc uses the UVC kernel driver, it uses the V4L2 events interface to communicate. Each event is mapped to specific callbacks and methods within the library and the user application in order to ensure the intercommunication.

'libGuvc API is quite simple, the following pseudo code depicts the basic sequence used on a typical user application. 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.

Can I use libGuvc with another gadget driver?

Since libGuvc uses the standard Linux driver for UVC, it works like any other USB gadget driver in the system. This means that you can set it up as a composite driver in order to get UVC function working alongside with other gadget functions such as UAC (audio over USB), mass storage, RNDIS, etc. For more information about USB gadget, composite drivers see USB gadget composite drivers.

Given that, using libGuvc with another gadget driver only requires to create a composite driver containing your desired functions and using each function independently in your userspace application. As an example please consider Figure 2 for a composite driver containing UVC and UAC functions. At the lower layer, there is a composite driver containing both functions, UVC and UAC, this exposes a /dev/videoX device for the UVC driver and a sound card for the UAC driver. Then, the user can stream video directly to the video node using libGuvc and at the same time, use the audio card to stream or record audio.


Figure 2. UVC composite driver example

Dependencies

LibGUVC needs the next dependencies to be fulfilled: 

 sudo apt install -y automake
 sudo apt install -y build-essential

If you want to use LibGUVC with GStreamer then fulfilled the next dependencies: 


 sudo apt install \
 gstreamer1.0-x \
 libgstreamer1.0-dev \
 libgstreamer-plugins-base1.0-dev \
 gstreamer1.0-plugins-bad \
 libgstreamer-plugins-bad1.0-dev \
 gstreamer1.0-nice \
 gstreamer1.0-plugins-ugly


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 sets of pre-defined video resolutions and runs only for about 5min before it disconnects the UVC session automatically.

If you are interested in testing the library please Contact Us

libGuvc in action

Running libGuvc in NVIDIA Jetson AGX Xavier

Running libGuvc in i.MX6


RidgeRun Resources

Quick Start Client Engagement Process RidgeRun Blog Homepage
Technical and Sales Support RidgeRun Online Store RidgeRun Videos Contact Us

OOjs UI icon message-progressive.svg Contact Us

Visit our Main Website for the RidgeRun Products and Online Store. RidgeRun Engineering informations are available in RidgeRun Professional Services, RidgeRun Subscription Model and Client Engagement Process wiki pages. Please email to support@ridgerun.com for technical questions and contactus@ridgerun.com for other queries. Contact details for sponsoring the RidgeRun GStreamer projects are available in Sponsor Projects page. Ridgerun-logo.svg
RR Contact Us.png
Retrieved from "http://developer.ridgerun.com/wiki/index.php?title=USB_Video_Class_Gadget_Library_-_libguvc&oldid=48932"