/**
\page yarpdev yarpdev: the standard YARP device utility

\ingroup yarp_tools

\tableofcontents

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.
The most important devices are enabled by default.
To disable all device plugins, you can set to `OFF` the
`YARP_COMPILE_DEVICE_PLUGINS` option in CMake.
You can select and deselect each device using the relative `ENABLE_*`
options in CMake.
Often this will require that you install
particular libraries or operating system device drivers.


\section yarpdev_base 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:

\verbatim
$ 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 fakeFrameGrabber --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
\endverbatim

\section yarpdev_list yarpdev --list

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

\verbatim
$ 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 "opencv_grabber", C++ class OpenCVGrabber, wrapped by "grabber"
Device "ffmpeg_grabber", C++ class FfmpegGrabber, wrapped by "grabber"
Device "fakeFrameGrabber", C++ class FakeFrameGrabber, 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.
Device "portaudioPlayer", available on request (found in <prefix>/lib/yarp/yarp_portaudioPlayer.so library), wrapped by "AudioPlayerWrapper".
Device "portaudioRecorder", available on request (found in <prefix>/lib/yarp/yarp_portaudioRecorder.so library), wrapped by "AudioRecorderWrapper".
\endverbatim

where the first keyword like "fakeFrameGrabber" 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.

\section yarpdev_normal yarpdev --device DEVICENAME --OPTION1 VALUE1 ...

This is the normal way to start up a device.  For example:
\verbatim
$ yarpdev --device fakeFrameGrabber --period 0.5 --width 640 --height 480
Test grabber period 0.5 / freq 2, mode [line]
yarpdev: created device <fakeFrameGrabber>.  See C++ class FakeFrameGrabber 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...
[...]
\endverbatim

Here we've asked to create the "fakeFrameGrabber" 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 "fakeFrameGrabber" 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 fakeFrameGrabber and other camera-like devices, this wrapper is
called "grabber".  In fact, our original request of:
\verbatim
$ yarpdev --device fakeFrameGrabber --period 0.5 --width 640 --height 480
\endverbatim
was automatically expanded to:
\verbatim
$ yarpdev --device grabberDual --subdevice fakeFrameGrabber --period 0.5 --width 640 --height 480
\endverbatim

\section yarpdev_verbose 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:
\verbatim
$ 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.
\endverbatim

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:
\verbatim
$ yarpdev --device ffmpeg_grabber --source your_movie.avi
\endverbatim
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:
\verbatim
$ 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.
\endverbatim
So now we see another level of configuration which we can
do to make the device match our system.

\section devices_parameters Detailed parameters description

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

For example the description for the

controlboardwrapper2 device is in the \ref dev_impl "Device implementation" -> Network Wrapper ->  \ref controlboardwrapper2_parameter "controlboardwrapper2 device page" \n
analogServer         device is in the \ref dev_impl "Device implementation" -> Network Wrapper ->  \ref analogServer_parameter "analogServer device page" \n
inertial             device is in the \ref dev_impl "Device implementation" -> Network Wrapper ->  \ref inertial_parameter "inertial device page" \n
batteryWrapper       device is in the \ref dev_impl "Device implementation" -> Network Wrapper ->  \ref batteryWrapper_parameter "batteryWrapper device page" \n
RGBDSensorWrapper    device is in the \ref dev_impl "Device implementation" -> Network Wrapper ->  \ref RGBDSensorWrapper_device_parameters "RGBDSensorWrapper device page" \n
grabberDual          device is in the \ref dev_impl "Device implementation" -> Network Wrapper ->  \ref grabberDual_device_parameters "grabberDual device page" \n

*/
