YARP
Yet Another Robot Platform
Definition of terms

Table of Contents

The YARP library supports transmission of a stream of user data across various protocols – TCP, UDP, MCAST (multi-cast), shared memory – insulating a user of the library from the idiosyncratic details of the network technology used.

We call these these low-level protocols the `‘Carriers’', to distinguish them from the higher-level protocols we will be concerned with here.

For the purposes of YARP, communication takes place through Connections'' between named entities calledPorts''. These form a directed graph, the `‘YARP Network’', where Ports are the nodes, and Connections are the edges.

Each Port is assigned a unique name, such as `‘/motor/wheels/left’'. Every Port is registered by name with a `‘name server’'. The goal is to ensure that if you know the name of a Port, that is all you need in order to be able to communicate with it from any machine.

The purpose of Ports is to move `‘Content’' (sequences of bytes representing user data) from one thread to another (or several others) across process and machine boundaries. The flow of data can be manipulated and monitored externally (e.g. from the command-line) at run-time. In other words, the edges in the YARP Network are entirely mutable.

A Port can send Content to any number of other Ports. A Port can receive Content from any number of other Ports. If one Port is configured to send Content to another Port, they are said to have a Connection. Connections can be freely added or removed, and may use different Carriers.

The YARP name server is a server that tracks information about ports. It indexes this information by name, playing a role analogous to DNS on the internet. To communicate with a port, the properties of that port need to be known (the machine it is running on, the socket it is listening on, the carriers it supports). The YARP name server offers a convenient place to store these properties, so that only the name of the port is needed to recover them.

Here are the specifications available in this document:

  • Properties of a YARP network.
  • Properties of the YARP utility.
  • Properties of the YARP name server and the protocol used for communicating with it.
  • Properties of ports and the protocol used for communicating with them.

Properties of a YARP network

A YARP network consists of the following entities: a set of ports, a set of connections, a set of names, a name server, and a set of registrations.

  • Every port has a unique name.
  • Every connection has a source port and a target port.
  • Each port maintains a list of all connections for which it is the target port.
  • Each port maintains a list of all connections for which it is the source port.
  • There is a single name server in a YARP network.
  • The name server maintains a list of registrations. Each registration contains information about a single port, identified by name.

Communication within a YARP network can occur between two ports, between a port and the name server, between a port and an external entity, and between the name server and an external entity.

  • Communication between two ports occurs if and only if there is a connection between them. That communication uses the `‘connection protocol’'.
  • Connections involving a port can be created, destroyed, or queried by communication between an external entity and that port. This is done by sending `‘port commands’' using the YARP connection protocol.
  • Ports communicate with the name server using the `‘YARP name server protocol’'. Such communication is needed to create, remove, and query registrations.
  • External entities can also use the YARP name server protocol to query the name server.

The standard YARP companion utility can be used to create a name server, and also to act as an external entity for querying and modifying the YARP network.