GstUsb

From RidgeRun Developer Connection
Revision as of 17:14, 2 September 2011 by Mgruner (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

GstUsb is a Gstreamer plugin that allows two pipelines communicate via USB link. The plugin contains the following elements:

  • UsbSrc
  • UsbSink

which act as sink and source elements for the respective pipelines. The philosophy behind GstUsb is to provide agnostic streaming or, in other words, the possibility to stream any kind of multimedia content using these elements.

Requirements

In order to use GstUsb there are several requirements you need to satisfy:

  • Platform with USB host capabilities. This can be your PC or an embedded system running a Linux kernel. Also, although it is not tested, GstUsb should work with an USB OTG port without problems.
  • Platform with USB gadget port. This will typically be an embedded system also running a Linux kernel. USB OTG works fine.
  • LibUSB API installed on the platform with host ports. LibUSB can be downloaded form here. This library con easily be ported for another architectures.
  • GadgetFS kernel module enabled in the gadget platform. This library is included in Linux kernel, but it's not activated by default. You probably will have to activate this module and recompile the kernel.
  • Gstreamer development libraries. Needed to compile GstUsb!
  • GstUsb source code. Currently this project is hosted on GitHub under BSD license. You can access the project site here

Setting up everything

Mounting GadgetFS

Once you have GadgetFS kernel module compiled, you must set up the virtual file system in order to GstUsb work properly. The following steps shows the correct process.

Important: These steps must be done on the gadget platform, the one running usbsrc and receiving the stream.

  • Create the VFS root for gadgetFS
# mkdir /dev/gadget
  • Insert GadgetFS kernel module
# modprobe gadgetfs
  • Mount the VFS
# mount -t gadgetfs none /dev/gadget

Or just,

Copy & Paste me!!!

(mkdir /dev/gadget && modprobe gadgetfs && mount -t gadgetfs none /dev/gadget && echo "GadgetFS ready") || echo "Unable to mount GadgetFS"

Adding LibUSB to pkg-config

When GstUsb is built, it will prompt por LibUSB installation using pkgconfig. This tool will provide the toolchain with the proper compilation and linker flags, among other information. If you have already LibUSB installed but the annoying installation error is still there, you should follow these steps:

Important: These steps must be done on the host platform, the one running usbsink and sending the stream.

  • Move into your pkg-config directory. This can be typically found on one of the following:

On host PC:

# cd /usr/lib/pkgconfig
# cd /usr/share/lib/pkgconfig

Using RidgeRun SDK:

# cd $DEVDIR/fs/fsdev/usr/lib/pkgconfig
  • Create an entry for LibUSB named "libusb-1.0.pc". Note that "1.0" should be replaced with the actual version you downloaded. Fill this file with the following:
#prefix should point to your installation dir
prefix=/home/mgruner/devdirs/bbxm.8.4.11/fs/fsdev/usr

exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include

#Fix version if needed
Name: libusb-1.0
Description: C API for USB device access from Linux userspace

#Fix version if needed
Version: 1.0.8

Libs: -L${libdir} -lusb-1.0
Cflags: -I${includedir}/libusb-1.0
  • Save and run build scripts again, you should not have problems.

Internal Functionality

General Overview

The USB link is configured with 3 endpoints:

  • Downstream events: Carries requests and return information from usbsink to usbsrc.
  • Upstream events: Carries requests and return information from usbsrc to usbsink.
  • Stream: Carries the multimedia stream.

Graphically, this can be appreciated in the next figure:

GstUsb.jpg

Based on this configuration, a continuous bidirectional request-answer system is achieved. This allows the initial handshake and other information exchange to be performed in a simple efficient way. One of the most important features of GstUsb plugin is its extended caps negotiation system.

Caps Negotiation

Although GstUsb has "ANY" capabilities and can stream whatever you want, the caps needed by de upstream pipeline must be the same as the ones needed by the downstream pipeline. GstUsb takes care of this automatically by extending the typical caps negotiation between elements, to a caps negotiation between pipelines. The following image explains the process.

GstUsb request.jpg
  1. The pipeline asks usbsink for its possible caps.
  2. Usbsink sends a "Get Caps" request to usbsrc.
  3. Usbsrc asks the possible caps of the pipeline.
  4. The pipeline returns the caps to usbsrc.
  5. Usbsrc answers usbsink sending back these caps.
  6. Usbsink sets these caps in the pipeline.

GstUsb handles the needed information exchange between pipelines the same way as the process above.

Plugin Details

The following and more detailed information can be found by typing:

# gst-inspect usbsink
# gst-inspect usbsrc

UsbSink

UsbSink is the element that sends the stream in the USB link. You will be using this as the sink element in your first pipeline.

Pads and Capabilities

It contains one always available Sink Pad. The capabilities of this pad are "ANY", which means you can stream whatever you want.

Properties

Usbsink offers the basic properties of a sink element and some specific implementations

Usbsink element properties
Property Description Type Default Value
name The name of the element String null
preroll-queue-len Number of buffers to queue during preroll UInt 0
sync Whether or not to synchronize with the clock. You should treat both usbsink's and usbsrc's pipelines as a single one, so for better results set this value to FALSE and sync with the the usbsrc's pipeline sink element. Bool TRUE
max-lateness Maximum number of nanoseconds that a buffer can arrive late before it's dropped. Int64 -1 (unlimited)
qos Generate Quality-of-Service events upstream. Bool FALSE
async Go asynchronously to paused Bool TRUE
ts-offset Timestamp offset in nanoseconds. This property will be overridden if usbsync is set to TRUE. Int64 0
enable-last-buffer Enables the last-buffer property Bool TRUE
last-buffer The last buffer in the sink GstBuffer ---
blocksize The size in bytes to read per buffer ULong 46
render-delay Additional render delay of the sink in nanoseconds UInt64 0
usbsync Fix buffer timestamps set the pipeline clock to be coherent with source's time. This property will override do-timestamp. To achieve optimal results set this property to TRUE in both usbsink and usbsrc. Bool TRUE


UsbSrc

UsbSrc is the element that receives the stream in the USB link. You will be using this as the source element in your second pipeline.

Pads and Capabilities

It contains one always available Src Pad. The capabilities of this pad are "ANY", which means you can stream whatever you want.

Properties

Usbsrc offers the basic properties of a source element and some specific implementations

UsbSrc element properties
Property Description Type Default Value
name The name of the element String null
blocksize The size in bytes to read per buffer ULong 46
num-buffers Number of buffers to output before sending EOS Int -1 (unlimited)
typefind Run typefind before negotiating Bool FALSE
do-timestamp Apply current stream time to to buffers. This time will be overriden is usbsync property is set to TRUE. Be careful! Bool FALSE
usbsync Fix buffer timestamps set by sink's clock to be coherent with source's time. This property will override do-timestamp. To achieve optimal results set this property to TRUE in both usbsink and usbsrc. Bool TRUE


Example pipelines

Video transmission

On host platform

# gst-launch videotestsrc ! usbsink sync=FALSE usbsync=TRUE --gst-debug=usbsink:5

On gadget platform

# gst-launch usbsrc usbsync=TRUE ! autovideosink --gst-debug=usbsrc:5

Audio transmission

On host platform

# gst-launch audiotestsrc ! usbsink sync=FALSE usbsync=TRUE --gst-debug=usbsink:5

On gadget platform

# gst-launch usbsrc usbsync=TRUE ! alsasink --gst-debug=usbsrc:5

Remote video mixing

On host platform

# gst-launch v4l2src ! usbsink sync=FALSE usbsync=TRUE --gst-debug=usbsink:5

On gadget platform

# gst-launch usbsrc usbsync=TRUE ! queue ! videomixer name=mix ! autovideosink  v4l2src ! queue ! mix. --gst-debug=usbsrc:5