Home

This repository consists of experimental software. You should not expect particularly high performance or reliability from any of the components within. Virtually all of the code in these components are written in Python and depend on various 'nice' language features like dynamic and duck typing and the ability to import additional libraries at runtime. A consequence of this functionality is that none of the software in this repository directly handles dependencies. Since the "dependencies" are set at runtime, the conventional ROS dependency process through catkin_make is not possible. As a result, you must manually ensure that the dependencies have been built!

With those issues said, the current components have been tested in a variety of ways and use cases.

Architecture

The goal of the teleoperation link components inside this repository is to produce a general-purpose, robust, easy-to-use, and as-high-performance-as-reasonable network relay system for ROS. The raison d'être for this software is that while ROS natively supports distributed networked systems, it does not do so in a way suitable for limited-bandwidth datalinks. Even with GbE links, one can easily saturate the datalink between a robot and user workstation. In particular, ROS provides no inherent support for deduplication of data flow (i.e. two subscribers each get their own copies of data sent over the same network link) and encourages the unnecessary sending of particularly heavy-weight data (e.x. TF) that can better be handled by generating it at either end of the link. Therefore, this software is designed to serve as relay that uses a combination of existing ROS transport mechanisms and newly developed ones to reduce the data demands and allow the use of multiple ROS system topographies (single-master and multi-master).

Note - this software, while enabling similar functionality to the ROS Multi-Master project, is completely different with different goals and development philosophy. Use these packages if you want a link system designed specifically for low-bandwidth operations, or use Multi-Master if you want a system that behaves as close to "normal" ROS as possible.

Design Philosophy

These packages aim to provide an ROS datalink that is virtually identical to the normal ROS system for publishers and subscribers. As always, you will publish and subscribe to topics. While the topics will obviously have different names, all functionality will be the same except for specific very rare cases.

Fair warning, this flexibility comes at a cost - these packages require significant thoughtful configuration for any non-trivial use cases. Every single topic to be relayed must be explicitly configured to go through the link packages, and malformed configurations can produce extremely hard-to-debug errors.

Additionally, this flexibility is achieved by using a large number of nodes - a general rule of thumb is that the nodes necessary for the link is 4n + 2 where n is the number of topics being sent over the relay. While planned enhancements will reduce this to 2n + 2 in most use cases, you must understand the processing requirements that result from this number of additional nodes (even if the nodes are quite simple).

Link Architecture

Each one-way sender->recipient link consists of several linked components:

Sender side:

1. rate_controller - this allows you to set the rate of sending a topic over the link from infinity (as fast as possible) to zero (stop flow).

2. link_startpoint - this handles automatically starting and stopping data flow for a topic depending on if subscribers are connected to the remote end or not.

3. message_serializer - this explicitly serializes the messages on a topic, adds a new human- and machine-readable header, and sends the serialized messages to be aggregated for transport.

4. message_multiplexer - this aggregates together various serialized messages and sends them over the data link in larger chunks. Only one message_multiplexer is needed to support a number of topics being relayed.

Recipient side:

1. message_demultiplexer - this separates out the various messages combined for transport, deserializes them, and republishes them on new topics. Only one message_multiplexer is needed to support a number of topics being relayed.

2. link_endpoint - this is the remote end of a topic's relay, and it controls automatic flow based on the presence of subscribers. This is also the noe that publishes the "final" relayed topic that client software will subscribe to.

Configuring a topic relay

Setting up the relay system for a topic can be deceptively complicated - in almost all configurations, the default settings reduce the number of user-configured parameters to 11 (5 sender-side, 6 recipient-side).

Examples of simple (and more complicated) configurations can be found in teleop_launch/launch

To set up the sender's side of a relay, you will include teleop_launch/launch/hybrid_link_start_chain.launch in your own launch file once for every topic you wish to relay and set the following arguments:

• chain_name - the name prefix for the nodes used to relay the current topic. The names are of the form <chain_name>_limiter, <chain_name>_serializer, etc.

• chain_type - the type of message data being sent, in the form of <package name>/<Message type> (e.x. std_msgs/String)

• input_topic - the "raw" source topic name on the sending side.

• aggregation_topic - the name for the aggregation topic onto which all messages will be sent.

• aggregated_topic - the name for the output topic for the message aggregator.

On the recipient side, you will include teleop_launch/launch/hybrid_link_end_chain.launch and set the following arguments:

• chain_name - the name prefix for the nodes used to relay the current topic. The names are of the form <chain_name>_limiter, <chain_name>_serializer, etc.

• chain_type - the type of message data being sent, in the form of <package name>/<Message type> (e.x. std_msgs/String)

• input_topic - the "raw" source topic name on the sending side.

• link_namespace - the namespace for messages republished by the demultiplexer/deserializer. If you do not set a namespace on a single-master system, you will get a circular subscription relationship and the relay will not work properly.

• relay_namespace - the namespace for all topics relayed to be republished on. If you do not set a namespace on a single-master system, you will get a circular subscription relationship and the relay will not work properly.

• latched - (default=false) sets whether or not a given topic is being published latched or not, and configures the link_endpoint accordingly to support latched behavior.

• aggregated_topic - the name for the output topic for the message aggregator.

Testing Guides

• Using Wireshark to analyze traffic