YARP  2.3.68+228-20170410.2+git7d0b2e0
Yet Another Robot Platform
Configuring YARP Connections
Author
Paul Fitzpatrick

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:

tcp carrier

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.

udp carrier

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.

mcast (multicast) carrier

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.

shmem (shared memory) carrier

You can establish a shared memory connection between two ports /src and /dest by typing:

yarp connect /src /dest shmem
Note
Such connections will not work unless the source and destination ports are on the same machine. That is the nature of shared memory.

The author of this documentation is not aware of any configuration options for this carrier.

local (within-process) carrier

You can establish a connection via shared process memory between two ports /src and /dest by typing:

yarp connect /src /dest local
Note
Such connections will not work unless the source and destination ports belong to the same process.

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.

text (text-mode across tcp) carrier

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.

text_ack (text-mode across tcp with acknowledgement) 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.

fast_tcp (tcp without acknowledgement) 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.

http 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.

mjpeg (mjpeg-over-http) carrier

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 CREATE_OPTIONAL_CARRIERS 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.

xmlrpc carrier

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:

  • XMLRPC int = Bottle int
  • XMLRPC string = Bottle string
  • XMLRPC double = Bottle double
  • XMLRPC array = Bottle list
  • XMLRPC struct = Bottle list

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:

  • publisherUpdate
  • requestTopic
  • getPid
  • getBusInfo

This is for ROS compatibility (see Using YARP with ROS).

tcpros carrier

This carrier is for interoperations with ROS. See Using YARP with ROS and http://www.ros.org/wiki/ROS/TCPROS

bayer carrier

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 test_grabber --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.