GstUsb

From RidgeRun Developer Connection

Revision as of 22:14, 2 September 2011 by Mgruner (Talk | contribs)
(diff) ← Older revision | Current 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:

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.

Contents

Requirements

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

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.

# mkdir /dev/gadget
# modprobe gadgetfs
# 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.

On host PC:

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

Using RidgeRun SDK:

# cd $DEVDIR/fs/fsdev/usr/lib/pkgconfig
#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

Internal Functionality

General Overview

The USB link is configured with 3 endpoints:

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
Navigation
Toolbox