YARP  2.3.68+230-20170426.1+git4c562a6
Yet Another Robot Platform
yarp: the main YARP command-line interface

The command-line utility "yarp" performs a set of useful operations for a YARP network.

It can give status information, make and break connections between ports, and send/receive data to/from ports. For an example of usage, see this section: An extended example.

Here are the ways you can call yarp:

yarp

The utility gives a friendly 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:

This is the YARP network companion.
Call with the argument "help" to see a list of ways to use this program.

yarp check

Does some sanity tests of your setup. If you run "yarp server" in one terminal, and then run this command ("yarp check") in another, you should see something like:

yarp: ==================================================================
yarp: === Trying to register some ports
yarp: ==================================================================
yarp: === Trying to connect some ports
yarp: Receiving input from /tmp/port/2 to /tmp/port/1 using tcp
yarp: Sending output from /tmp/port/2 to /tmp/port/1 using tcp
yarp: ==================================================================
yarp: === Trying to write some data
yarp: ==================================================================
yarp: === Trying to read some data
yarp: *** Read number 42
yarp: ==================================================================
yarp: === Trying to close some ports
yarp: Removing input from /tmp/port/2 to /tmp/port/1
yarp: Removing output from /tmp/port/2 to /tmp/port/1
yarp: *** YARP seems okay!

yarp clean

yarp clean
yarp clean --timeout 10

This command gets a list of all registered ports from the name server, and checks them one by one to see if they are responding (using yarp exists). If they do not respond within a few seconds they are unregistered (using yarp name unregister).

If you run into troubles with this command seeming to hang on a port name (in fact it is a very loooooong timeout), you may want to unregister that port name yourself. Alternatively, you may specify a timeout in seconds after which YARP should give up on reaching a port.

yarp cmake

yarp cmake

Generates a "CMakeLists.txt" that is suitable for compiling code with YARP. It is intended to help new users get started on new projects quickly.

yarp conf

  yarp conf
  yarp conf --clean
  yarp conf IP SOCKETPORT

This will report the location of the file in which the name server location is configured. For the author's machine, the result is:

/home/paulfitz/.config/yarp/conf/yarp.conf

If the YARP_CONF directory is set, this will be where the conf/yarp.conf file is created/read. The first line of that file looks like this:

 15.255.112.22 10000

This is simply the IP address and the port number of the yarp name server. The file can be modified by hand, but will be overwritten if the name server does not respond and is discovered running somewhere else. You are also free to delete the file, which will force autodetection of the server.

The name of this file will be different if namespaces are in use. The file will be in the same directory, but its name will be the name of the namespace, with all non-alphanumeric characters replaced by "_", and ".conf" appended.

With the "--clean" option, the configuration file will be set to a blank, empty state.

If an ip address and socket port number for the name server are supplied, the configuration file will be rewritten to contain that information.

yarp connect

yarp connect OUTPUT_PORT INPUT_PORT
yarp connect OUTPUT_PORT INPUT_PORT CARRIER
yarp connect --persist OUTPUT_PORT INPUT_PORT
yarp connect --persist OUTPUT_PORT INPUT_PORT CARRIER
yarp connect --persist TOPIC INPUT_PORT
yarp connect --persist OUTPUT_PORT TOPIC
yarp connect --persist PORT
yarp connect --persist

This will request the specified output port to send its output in future to the specified input port. Optionally, the carrier to be used can be added as an extra argument (e.g. tcp, udp, mcast, ...). Ordinarily, ports must already exist in order to be connected, and connections last until one of the ports is removed (or the connection is removed with yarp disconnect). If "--persist" is specified, the ports do not need to already exist, they will be connected whenever they are both present. A list of all persistent connections involving a port can be retrieved by providing the name of that port alone. A list of all persistent connections can be retrieved by omitting port names completely. Persistent connections can be made to bundles of ports called "topics", see yarp topic.

yarp detect

  yarp detect
  yarp detect --write

This will search for the YARP name server using multicast.

With the "--write" option, a configuration file will be written with the address for the name server, if found. This will let regular YARP programs find the name server.

yarp disconnect

yarp disconnect OUTPUT_PORT INPUT_PORT

This will request the specified output port to cease sending its output to the specified input port.

yarp exists

yarp exists /PORT

Check if a port is alive. This can be useful as a quick test of whether the process that owns the port is running. It is designed for use in scripts – nothing is printed, the result is encoded in the return value of the program (0 = port exists).

A variant of this command checks if a connection between two ports exists:

yarp exists /SOURCE_PORT /TARGET_PORT

yarp help

This lists a human-readable summary of the ways the utility can be used. It is a short version of what you are reading right now.

yarp merge

  yarp merge /PORT1 /PORT2
  yarp merge --input /PORT1 /PORT2 --output /PORT3 --worker /PORT/PREFIX --carrier udp

This command merges input from several ports into a single message, sending that on from an output port.

yarp name

yarp name COMMAND ARG_1 ARG_2 ...

This will send the given command and arguments to the YARP name server and report the results. Here are the possible commands:

For example:

# user types...
yarp name list
   # system responds...
   registration name root ip 172.16.232.1 port 10000 type text
   registration name fallback ip 224.2.1.1 port 10001 type mcast
   registration name /read ip 172.16.232.1 port 10002 type tcp
   registration name /write ip 172.16.232.1 port 10012 type tcp
   *** end of message

This is equivalent to:

# user types...
yarp where
   # system responds...
   Name server is available at ip 172.16.232.1 port 10000
   Name server can be browsed at http://172.16.232.1:10000/
# user types...
telnet 172.16.232.1 10000
   # system responds...
   Trying 172.16.232.1...
   Connected to 172.16.232.1.
   Escape character is '^]'.
# user types...
NAME_SERVER list
   # system responds...
   registration name /read ip 172.16.232.1 port 10002 type tcp
   registration name root ip 172.16.232.1 port 10000 type text
   registration name fallback ip 224.2.1.1 port 10001 type mcast
   registration name /write ip 172.16.232.1 port 10012 type tcp
   *** end of message
# user types...
^]
   # system responds...
   telnet> quit
   Connection closed.

yarp name help

This will list the commands available from the name server. For example, our current implementation gives:

Here are some ways to use the name server:
  NAME_SERVER register ...
  NAME_SERVER unregister ...
  NAME_SERVER query ...
  NAME_SERVER help ...
  NAME_SERVER set ...
  NAME_SERVER get ...
  NAME_SERVER check ...
  NAME_SERVER match ...
  NAME_SERVER list ...
  NAME_SERVER route ...
*** end of message

yarp name query

yarp name query PORT

Requests registration information for the named port. Response is of the following form:

registration name PORT ip ADDRESS port NUMBER type CARRIER
*** end of message

For example:

registration name /write ip 5.255.112.227 port 10001 type tcp
*** end of message

If there is no registration for the port, the registration line is omitted, and instead the response is simply:

*** end of message

yarp name register

yarp name register PORT
yarp name register PORT CARRIER
yarp name register PORT CARRIER IP
yarp name register PORT CARRIER IP NUMBER

Requests creation of registration information for the named port. Response is of the following form:

registration name PORT ip ADDRESS port NUMBER type CARRIER
*** end of message

For example:

registration name /write ip 5.255.112.227 port 10001 type tcp
*** end of message

Optionally, the user can take responsibility for more fields, such as the carrier, ip, and socket port number. Any value (including the port name) can be replaced by ``...'' to leave it up to the name-server to choose it. For example:

yarp name register ... tcp 127.0.0.1 8080

Gives something of the form:

registration name /tmp/port/1 ip 127.0.0.1 port 8080 type tcp
*** end of message

If you choose to set the ip yourself, be careful – there is the possibility of problems with multiple ways to identify the same machine. It is best to let the name server choose a name, which it should do in a consistent way. If a machine has multiple ip addresses on multiple networks, that can be handled – see the discussion of the ips property in the section on "yarp name set". That is important for the purposes of controlling which network is used for connections from one port to another.

yarp name unregister

yarp name unregister PORT

Removes registration information for the named port. Response is of the following form:

*** end of message

yarp name list

Gives registration information of all known ports. Response is of the following form:

registration name /write ip 130.251.4.159 port 10021 type tcp
registration name /read ip 130.251.4.159 port 10031 type tcp
registration name /tmp/port/4 ip 130.251.4.159 port 10011 type tcp
registration name /tmp/port/3 ip 130.251.4.52 port 10021 type tcp
registration name /tmp/port/2 ip 130.251.4.52 port 10011 type tcp
registration name /tmp/port/1 ip 130.251.4.159 port 10001 type tcp
*** end of message

yarp name set

yarp name set PORT PROPERTY VALUE1 VALUE2 ...

The name server can store extra properties of a port, beyond the bare details associated with registration. The set command is used to do this. For example, the command:

yarp name set /write offers tcp udp mcast

Gets the following response:

port /write property offers = tcp udp mcast

The get and check commands can then be used to query such properties.

There are some special properties used by YARP. Property ips'' can list multiple identifiers of a machine. Propertyoffers'' lists carriers that an output port can support. Property ``accepts'' lists carriers that an input port can support.

yarp name get

yarp name get PORT PROPERTY

Gets the values of a stored property. For example, after the set command example shown earlier, the command:

yarp name get /write offers

Returns the following response:

port /write property offers = tcp udp mcast

yarp name check

yarp name check PORT PROPERTY VALUE

Checks if a stored property can take the given value. For example, after the set command example shown earlier, the command:

yarp name check /write offers tcp

Returns the following response:

port /write property offers value tcp present true

yarp name route

yarp name route PORT1 PORT2

Finds a good way to connect an output port to an input port, based on the carriers they have in common (preferred carriers can optionally be added to this command in decreasing order of preference) and which carriers are physically possible (for example, `shmem' requires ports to be on the same machine, and `local' requires ports to belong to threads with a shared memory space). For example, the command:

yarp name route /write /read

Returns the following response:

port /write route /read = shmem://read

This suggests that shmem is the best carrier to use.

yarp name gc

THIS COMMAND IS DEPRECATED, use yarp clean instead.

yarp name gc

This requests that the server "garbage collect" any registered ports that are no longer responding. This is useful for cleaning up registrations corresponding to programs that have crashed or been terminated abruptly. THIS COMMAND IS DEPRECATED, use yarp clean instead.

yarp namespace

yarp namespace
yarp namespace /namespace

The yarp name server started by yarp server has a port name associated with it. By default, this is "/root". This can be changed, and it is useful to do so when a single network is shared by people working on non-overlapping projects involving YARP.

Type "yarp namespace" to report the current namespace.

Type "yarp namespace /my/space" to set the namespace to "/my/space".

See About YARP Namespaces for (important) details on how to use namespaces.

yarp ping

yarp ping /PORT
yarp ping --time /PORT
yarp pint --rate /PORT

Get information about the specified port (optionally: timing and rate). Result will be something like:

This is "/port" at "tcp://192.168.0.5:10012"
There is an output connection from "/write" to "/read" using tcp
There is an input connection from "<ping>" to "/write" using text_ack

The option –time reports timing measure about communication with the port.

The option –rate reports the rate at which information arrives from the port.

yarp read

yarp read INPUT_PORT [envelope]
yarp read INPUT_PORT [envelope] OUTPUT_PORT

This will create an input port of the specified name. It will then loop, reading ``yarp bottles'' (a simple serialized list) and printing their content to standard output. This simple utility is intended for use in testing, and getting familiar with using YARP.

For example, if you run "yarp server" in one terminal, "yarp read /read" in another, and "yarp write /write verbatim /read" in another, then everything you type on the "write" terminal will be echoed on the "read" terminal.

Specifying an OUTPUT_PORT tries to connect that port to the current one.

Adding the "envelope" tag will request display of any envelope information included in the message, such as timestamps. Such information may or may not be present, and is ignored if you do not specify this tag.

yarp regression

  yarp regression
  yarp regression <ClassName>Test

Runs all tests or a specified test, if the YARP regression tests are linked. Normally, there are separate programs called "harness_os", "harness_sig", etc that have groups of YARP tests linked. So running:

  harness_os regression

will run all tests related to libYARP_OS. The main YARP executable "yarp" does not usually have any tests linked.

yarp resource

  yarp resource --context CONTEXT --from CONFIG.ini

An experimental tool for finding configuration files and other resource files. For details, see the yarp::os::ResourceFinder class.

yarp rpc

yarp rpc /TARGET_PORT
yarp rpc /TARGET_PORT /LOCAL_NAME

This will send a message to the target port and expect a response. Useful only if you have a port that actually will respond. Ports associated with devices may behave like this. You may optionally specify the name for the connection. "RPC" stands for Remote Procedure Call.

An example of a port that will respond to RPC is the yarp server. For example, if you run:

yarp rpc /root

and type:

list

you'll receive a response like:

Response: registration name /root ip 192.168.0.204 port 10000 type tcp
Response: registration name fallback ip 224.2.1.1 port 10001 type mcast
Response: *** end of message

See yarp name for other commands the name server responds to.

yarp rpcserver

yarp rpcserver /PORT_NAME

This creates a test RPC server. It will accept incoming commands, and then pause for you to type the response (in standard Bottle text format).

yarp run

yarprun provides a client-server environment that is able to run, kill and monitor applications on a remote machine, with the same syntax and behaviour in Windows and Linux.

See yarprun: run programs on a set of machines for documentation.

yarp sample

  yarp sample --output /OUTPUT/PORT --period 0.1
  yarp sample --output /OUTPUT/PORT --rate 100
  yarp sample --input /INPUT/PORT --output /OUTPUT/PORT --period 0.1 --carrier udp
  yarp sample --output /OUTPUT/PORT --rate 100 --show

This command repeats data on the output port at the specified rate (in Hz) or period (in seconds). If the show flag is given, the data is also printed on standard output. The input can either be connected externally or specified with –input (and optionally –carrier to specify the type of connection to use).

yarp server

This starts a name server running on the current machine. See yarpserver documentation for the options accepted by this command.

yarp terminate

yarp terminate /PORTNAME

This will request the specified output to interrupt the process it belongs to. In general, this requires active cooperation from that process, so it may or may not function. Currently will work for the ".../quit" ports created by the yarpdev process.

yarp topic

yarp topic /TOPIC_NAME
yarp topic --remove /TOPIC_NAME
yarp topc --list

Activates a topic name. If a sufficiently recent yarp name server is in use, then that topic name will act as a virtual repeater port. If a persistent connection exists between ports /A, /B and /C and /TOPIC, and from /TOPIC to /X, /Y, and /Z, then ports /X, /Y, and /Z will each receive input from all of /A, /B, and /C. See Persistent connections.

yarp version

This will report on the yarp version available. Example:

YARP Companion utility version 2.0 implemented in C++

yarp wait

yarp wait /PORT
yarp wait /SRC /DEST

Waits for the named port or connection to come into existence. Terminates when "yarp exists /PORT" or "yarp exists /SRC /DEST" would return true. This can be useful in scripts.

yarp where

This will report where the name server is believed to be running; for example:

Name server is available at ip 15.255.112.22 port 10000
Name server can be browsed at http://15.255.112.22:10000/

The name server registers this address with itself under the name "/root". So typing:

yarp name query /root

will get the same information. See yarp name query.

This command used to search for the name server if needed, but now you need to explicitly request that with the name_detect command.

yarp write

yarp write OUTPUT_PORT [verbatim]
yarp write OUTPUT_PORT [verbatim] INPUT_PORT1 INPUT_PORT2 ...

This will create an output port of the specified name. It will then loop, reading from standard input and writing yarp bottles. Optionally, a list of input ports to connect to automatically can be appended to the command. This simple utility is intended for use in testing, and getting familiar with using YARP.

If the "verbatim" keyword is included after the OUTPUT_PORT name, then input from standard input will be transmitted as a string, rather than as a bottle. This will preserve the exact text with whitespace and quoting. Otherwise the input is interpreted as a list of values that are transmitted in a standard network format that will not preserve whitespace, quoting, and other features.

For example, if you run "yarp server" in one terminal, "yarp read /read" in another, and "yarp write /write verbatim /read" in another, then everything you type on the "write" terminal will be echoed on the "read" terminal.

An extended example

Start five terminals, called A-E. Do the following:

[in terminal A] yarp server
[in terminal B] yarp check

Terminal B should run some tests, then say yarp is "ok". Now do the following, leaving terminal A untouched:

[in terminal B] yarp read /read
[in terminal C] yarp write /write verbatim /read

Now type some stuff into terminal C and hit return. That stuff should be echoed on terminal B. Now try:

[in terminal D] yarp disconnect /write /read

Now if you type stuff in terminal C, it no longer appears on B. Now try:

[in terminal D] yarp connect /write /read

Now if you type stuff in terminal C, it appears on B again.

If you have the "yarpdev" and "yarpview" programs, we can go further. Try:

[in terminal E] yarpdev --device test_grabber --period 2 --width 8 --height 8 --name /grabber

This creates a test "device" with a port called "/grabber", outputting a very small test image every 2 seconds. You won't see much happen yet. Try:

[in terminal D] yarpview --name /view &
[in terminal D] yarp connect /grabber /view

You should now see a slow-moving red line. Try:

[in terminal D] yarp connect /grabber /read

You should now see a text representation of the image on terminal B appearing every 2 seconds.

See also: yarpdev: the standard YARP device utility yarpview: visualize YARP images