 |
YARP
Yet Another Robot Platform
|
|
|
YARP
Yet Another Robot Platform
|
|
Every YARP connection has a specific type of carrier associated with it.
This corresponds roughly to the "transport" used to carry data. For example there is the tcp carrier, the udp carrier, the mcast (multi-cast) carrier. For each transport, there can be several variants of carrier. For example, across tcp, there can be the basic binary-mode tcp carrier, or the text (text-mode) carrier, or the fast_tcp carrier which takes some shortcuts for speed.
Before using carriers other than the default, please do make sure you understand the performance of your network and check that it is configured well - see Setting up your network for YARP.
Here we look at configuration issues that arise for individual carriers.
Optional carriers:
This is the default carrier for YARP connections. It doesn't really need much configuration. For two ports, /src and /dest, you can establish a tcp connection between them by typing:
yarp connect /src /dest
or equivalently:
yarp connect /src /dest tcp
If the two ports are on separate computers connected by multiple networks, the network the connection uses may not be the one you'd prefer. If you want to control this, you can prepend "/net=IP-PREFIX/" to the target port name. For example, a name such as "/net=196/write" means "connect to the port named /write using the network with ip addresses beginning with 196''. See YARP URIs.
You can establish a UDP connection between two ports /src and /dest by typing:
yarp connect /src /dest udp
The udp carrier is unreliable (by the nature of the underlying UDP protocol). However, on a local network under controlled conditions UDP can be a very efficient method for moving data.
The udp carrier is unidirectional; it should be used for streaming messages rather than RPC (remote procedure call) send/reply sequences.
YARP will discard messages with corrupted, missing, duplicated, or out-of-order parts, so the only problem you should have is messages simply failing to arrive.
If you have multiple networks, you can control which networks individual connections use with the same method described for the tcp carrier.
The steps described in Setting up your network for YARP are very important if you will be sending large YARP messages using udp.
Large messages are broken into a series of datagrams. You can control the size of those datagrams in bytes by setting the environment variable YARP_DGRAM_SIZE (to control both udp and multicast together) or YARP_UDP_SIZE (to control just udp datagram size). The right setting for this number depends a lot on what you want to do. It is worth experimenting across quite a large range, say from 5000 to 120000 or more.
You can establish a multicast connection between two ports /src and /dest by typing:
yarp connect /src /dest mcast
CAREFUL: multicast is not supported by all all network hardware, and even when it is, support can be a bit hit-and-miss.
For multiple ports reading from the same source, YARP will map these logical connections to a single multicasting source.
The mcast carrier is unreliable (by the nature of the underlying multicast protocol). However, on a local network under controlled conditions multicast can be a very efficient method for moving data.
The mcast carrier is unidirectional; it should be used for streaming messages rather than RPC (remote procedure call) send/reply sequences.
YARP will discard messages with corrupted, missing, duplicated, or out-of-order parts, so the only problem you should have is messages simply failing to arrive.
If you have multiple networks, you can control which networks individual connections use with the same method described for the tcp carrier.
The steps described in Setting up your network for YARP are very important if you will be sending large YARP messages using mcast.
Large messages are broken into a series of datagrams. You can control the size of those datagrams in bytes by setting the environment variable YARP_DGRAM_SIZE (to control both udp and multicast together) or YARP_MCAST_SIZE (to control just multicast datagram size). The right setting for this number depends a lot on what you want to do. It is worth experimenting across quite a large range, say from 5000 to 120000 or more.
You can establish a shared memory connection between two ports /src and /dest by typing:
yarp connect /src /dest shmem
The author of this documentation is not aware of any configuration options for this carrier.
You can establish a connection via shared process memory between two ports /src and /dest by typing:
yarp connect /src /dest local
For ports that are in control of message allocation and reuse (i.e. BufferedPort ports), this is a very efficient carrier. The messages held by source and destination ports are placed into a merged pool with zero copies needed.
You can establish a text-mode connection between two ports /src and /dest by typing:
yarp connect /src /dest text
This is a reliable TCP connection. This is useful if the destination port is not actually a YARP port, but a socket being read by a non-YARP program. Text-mode messages are particularly easy to read (see YARP without YARP).
This type of connection does not contain acknowledgements to the sender of data received. If this is a problem, use the text_ack carrier.
You can establish a text-mode connection between two ports /src and /dest by typing:
yarp connect /src /dest text_ack
This is a reliable TCP connection. This is useful if the destination port is not actually a YARP port, but a socket being read by a non-YARP program. Text-mode messages are particularly easy to read (see YARP without YARP).
This type of connection has acknowledgements to the sender of data received, unlike the text carrier.
You can establish a binary-mode tcp connection without acknowledgements between two ports /src and /dest by typing:
yarp connect /src /dest fast_tcp
This can be useful to get a bit more speed in cases where flow is producer-limited, not consumer-limited. In general though it is safer to use the regular tcp carrier.
This is a carrier for use from web browsers. It is not intended for port-to-port connections. See YARP ports from your browser for details.
This carrier is for transporting images only. It is handy for reading directly from IP cameras, or streaming images to a browser (most modern browsers can directly render mjpeg-over-http streams). See Viewing images in a browser.
yarp connect /src /dest mjpeg
To compile this carrier, turn on YARP_COMPILE_CARRIER_PLUGINS and then ENABLE_yarpcar_mjpeg_carrier in CMake. There will be an extra CMake option called MJPEG_AUTOCOMPRESS. If turned on, this carrier will deliver images of standard YARP image format to ports. If turned off, this carrier will deliver blobs that can be read by yarp::os::ManagedBytes or yarp::os::Bottle. See yarp::mjpeg::MjpegDecompression for helper functions. The motivation for disabling automatic decompression is to reduce load for clients that need to read images only occasionally.
This carrier transmits and receives messages in XMLRPC format.
yarp connect /src /dest local
Messages are automatically converted to and from Bottle-compatible format. Here is the mapping used:
Both arrays and structures in XMLRPC are mapped to Bottle lists. Structures are mapped to a list with the tag "dict" prepended, followed by sublists with key-value mappings:
(dict (key1 val1) (key2 val2))
The yarp::os::Bottle find/findGroup/check methods will work fine on such lists, or you could populate a Property object if you want fast look-up.
If you want to convert a Bottle list that may start with the string "dict" or "list", prepend the keyword "list".
(list ...)
That keyword will be silently consumed, and will guarantee that an XMLRPC array is produced.
XMLRPC messages that start with a string may be treated as an administrative message (and not passed on to the client reading from a port) if the initial string is one of the following:
This is for ROS compatibility (see Using YARP with ROS).
This carrier is for interoperations with ROS. See Using YARP with ROS and http://www.ros.org/wiki/ROS/TCPROS
The bayer carrier converts bayer images to rgb images on the receiver's side of a connection. It is a modifying carrier, and so can be used in combination with other carriers. For example, suppose port /grabber is streaming bayer images. For concreteness, here's a test program to do that (back.ppm is an arbitrary test image in PPM format):
yarpdev --device fakeFrameGrabber --src back.ppm --bayer --name /grabber
Suppose we start an image viewer and look at the stream from /grabber, using (for example) udp:
yarpview /view yarp connect /grabber /view udp
We will see a monochrome, speckled image (a bayer image). We can now reconnect with a connection that is configured to "debayer" the image on the receiver side:
yarp connect /grabber /view udp+recv.bayer
We should now see a color image. To use a downsampling debayer algorithm, we can do:
yarp connect /grabber /view udp+recv.bayer+size.half
or equivalently:
yarp connect /grabber udp+recv.bayer+size.half://view
If we are reading from a source using a non-default bayer color ordering, we can also specify this with the "order" carrier modifier:
yarp connect /grabber /view udp+recv.bayer+order.bggr
This says the first pixel on the first row is a blue color, followed by green. On the second row, the first pixel is green, followed by red.
Debayer filters from libdc1394 are supported, and can be specified using the "method" carrier modifier:
yarp connect /grabber /view tcp+recv.bayer+method.vng
Available methods: bilinear, hqlinear, downsample, vng, ahd, nearest, simple.
1.8.20