YARP  2.3.68+225-20170329.5+gitb0d3289
Yet Another Robot Platform
yarpdev: the standard YARP device utility

The command-line utility "yarpdev" can create devices and wrap them for network visibility.

This is useful in cases where you wish to control devices on remote machines.

The devices available to "yarpdev" depend on the options set when compiling YARP. To choose the devices you want compiled, run "ccmake ." (on UNIX) or "cmake" (on Windows) on the root directory of the YARP source code and select the "CREATE_DEVICE_LIBRARY_MODULES" option. After you configure, new "ENABLE_*" options will appear that permit you to choose what devices you want to try and compile. Often this will require that you install particular libraries or operating system device drivers.

yarpdev

The utility gives a message if called with no arguments to confirm that it exists, and to give tips on where to get started using it. Our current implementation says:

$ yarpdev
Welcome to yarpdev, a program to create YARP devices
To see the devices available, try:
   yarpdev --list
To create a device whose name you know, call yarpdev like this:
   yarpdev --device DEVICENAME --OPTION VALUE ...
For example:
   yarpdev --device test_grabber --width 32 --height 16 --name /grabber
You can always move options to a configuration file:
   yarpdev [--device DEVICENAME] --file CONFIG_FILENAME
If you have problems, you can add the "verbose" flag to get more information
   yarpdev --verbose --device ffmpeg_grabber

yarpdev --list

With the –list option present, the devices available on your system are listed. For example:

$ yarpdev --list
Here are devices listed for your system:
Device "dragonfly", C++ class DragonflyDeviceDriver, wrapped by "grabber"
Device "esd", C++ class EsdMotionControl, wrapped by "controlboard"
Device "esd_sniffer", C++ class EsdMessageSniffer, has no network wrapper
Device "microphone", C++ class MicrophoneDeviceDriver, wrapped by "grabber"
Device "inertiacube2", C++ class InertiaCube2, has no network wrapper
Device "jamesarmcalibrator", C++ class JamesArmCalibrator, has no network wrapper
Device "jameshead", C++ class JamesHead, has no network wrapper
Device "XSensMTx", C++ class XSensMTx, wrapped by "inertial"
Device "portaudio", C++ class PortAudioDeviceDriver, wrapped by "grabber"
Device "opencv_grabber", C++ class OpenCVGrabber, wrapped by "grabber"
Device "ffmpeg_grabber", C++ class FfmpegGrabber, wrapped by "grabber"
Device "test_grabber", C++ class TestFrameGrabber, wrapped by "grabber"
Device "remote_grabber", C++ class RemoteFrameGrabber, wrapped by "grabber"
Device "grabber", C++ class ServerFrameGrabber, is a network wrapper.
Device "inertial", C++ class ServerInertial, is a network wrapper.
Device "sound_grabber", C++ class ServerSoundGrabber, is a network wrapper.
Device "remote_controlboard", C++ class RemoteControlBoard, wrapped by "controlboard"
Device "controlboard", C++ class ServerControlBoard, is a network wrapper.

where the first keyword like "test_grabber" is the device name used to instantiate it, class is the name of the class that implements it and the latter explains if the device is a network wrapper or it has a default network wrapper to be used or it does not have a default wrapper.

yarpdev --device DEVICENAME --OPTION1 VALUE1 ...

This is the normal way to start up a device. For example:

$ yarpdev --device test_grabber --period 0.5 --width 640 --height 480
Test grabber period 0.5 / freq 2, mode [line]
yarpdev: created device <test_grabber>.  See C++ class TestFrameGrabber for documentation.
yarp: Port /grabber listening at tcp://130.251.4.155:10032
Grabber for images
No framerate specified, polling the device
yarpdev: created wrapper <grabber>.  See C++ class ServerFrameGrabber for documentation.
yarpdev: device active...
yarpdev: device active...
[...]

Here we've asked to create the "test_grabber" device, which acts as a fake image source. We've specified the image size and the rate at which images are created. The yarpdev program eventually said "device active" – this is a good sign.

The program reported that the "test_grabber" device was created. It also mentions a "grabber" device that is also created. Why is this? It is because most devices themselves know nothing about the network; instead they need to be "wrapped" in a special "network wrapper device" that knows how to put them on the network. For test_grabber and other camera-like devices, this wrapper is called "grabber". In fact, our original request of:

$ yarpdev --device test_grabber --period 0.5 --width 640 --height 480

was automatically expanded to:

$ yarpdev --device grabber --subdevice test_grabber --period 0.5 --width 640 --height 480

yarpdev --verbose --device DEVICENAME ...

If we add the "--verbose" flag, yarpdev will report information about device configuration. This can help a lot to work out what properties a device takes. For example, suppose we notice in the documentation that there is an "ffmpeg_grabber" which can read images from an avi file. But what options should we supply it? To find out, just add the "--verbose" flag and try to create the device without any options:

$ yarpdev --verbose --device ffmpeg_grabber
Could not open avi file default.avi
yarpdev: ***ERROR*** driver <ffmpeg_grabber> was found but could not open
yarpdev: ***ERROR*** driver <grabber> was found but could not open
===============================================================
== Options checked by device:
==
device=ffmpeg_grabber
grabber.subdevice=ffmpeg_grabber
    name (or nested configuration) of device to wrap
ffmpeg_grabber.device=ffmpeg_grabber
ffmpeg_grabber.source [default.avi]
    movie file to read from
ffmpeg_grabber.v4l
    if present, read from video4linux
ffmpeg_grabber.ieee1394
    if present, read from firewire
grabber.device=grabber
==
===============================================================
yarpdev: ***ERROR*** device not available.
Suggestions:
+ Do "yarpdev --list" to see list of supported devices.
+ Or append "--verbose" option to get more information.

The "--verbose" option adds the "options checked by device" information. We see that for the ffmpeg_grabber, there is an option called "source" which defaults to "default.avi" and is the "movie file to read from". Now if we do:

$ yarpdev --device ffmpeg_grabber --source your_movie.avi

The device starts correctly.

The "--verbose" information also mentioned an option called "v4l" with the comment "if present, read from video4linux". If we try adding this option, yarpdev may or may not succeed (depending on whether video4linux is present and how it is configured on your machine). A typical failed output is:

$ yarpdev --verbose --device ffmpeg_grabber --v4l
/dev/video0: No such file or directory
Could not open Video4Linux input
yarpdev: ***ERROR*** driver <ffmpeg_grabber> was found but could not open
yarpdev: ***ERROR*** driver <grabber> was found but could not open
===============================================================
== Options checked by device:
==
device=ffmpeg_grabber
grabber.subdevice=ffmpeg_grabber
    name (or nested configuration) of device to wrap
ffmpeg_grabber.device=ffmpeg_grabber
ffmpeg_grabber.source [default.avi]
    movie file to read from
ffmpeg_grabber.v4l
    if present, read from video4linux
ffmpeg_grabber.v4ldevice [/dev/video0]
    device name
ffmpeg_grabber.channel [0]
    channel identifier
ffmpeg_grabber.standard [ntsc]
    pal versus ntsc
ffmpeg_grabber.width [640]
    width of image
ffmpeg_grabber.height [480]
    height of image
ffmpeg_grabber.time_base_den [29]
    denominator of basic time unit
ffmpeg_grabber.time_base_num [1]
    numerator of basic time unit
grabber.device=grabber
==
===============================================================
yarpdev: ***ERROR*** device not available.
Suggestions:
+ Do "yarpdev --list" to see list of supported devices.
+ Or append "--verbose" option to get more information.

So now we see another level of configuration which we can do to make the device match our system.

Detailed parameters description

Each device class has a description page where input parameters are desribed in more detail. You can find a list of devices in Device implementation page subdivided by type.

For example the description for the

yarp::dev::controlBoardWrapper2 device is in the Device implementation -> Network Wrapper -> ControlBoardWrapper2 page
yarp::dev::analogWrapper device is in the Device implementation -> Network Wrapper -> analogWrapper page
yarp::dev::ServeriInertial device is in the Device implementation -> Network Wrapper -> ServeriInertial page