Home
This repository consists of experimental software. While the important components have been extensively tested and are used daily for our DRC team, they may exhibit undesirable and unexpected behavior. Many of 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.
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 that is directly 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. Some types of eduplication and relaying can be accomplished using ROS's topic_tools package, but configuring these relays for complex systems is non-trivial. This software provides a set of relays using established ROS transport mechanisms (topics and services) designed to reduce bandwidth usage and gracefully operate in low-bandwidth scenarios.
Note - Certain experimental components enable multi-master distributed operation - however, these components were not used for the DRC, and they are not covered in the documentation.
The core architecture of this software consists of links that relay an ROS topic from one computer to another. Each link has two parts:
-
link_startpoint - Subscribes to the original topic. This node should be run on the computer where the original topic is published.
-
link_endpoint - Republishes the topic at the other end of the link. Using services, it controls the flow and rate of data that it republishes. Connected to the startpoint, it automatically controls the flow of data depending on how many subscribers are connected.
This general architecture can be seen in the diagram below. link_startpoints and link_endpoints are shown in the magenta box.
Two variants of this link architecture are implemented:
-
limited This variant uses topics as the transport mechanism, with the endpoint setting the publish rate. This variant offers slightly higher data rates, but should only be used on networks with at approximately 2 Mb/s or more available bandwidth. Depending on message rate and type, this type of link can result in unexpectedly high network congestion in very low-bandwidth use cases.
-
request This variant uses services as the transport mechanism. Each message is requested and returned by service call. This design works better at low bandwidth (<< 1Mb/s), and gracefully degrades performance as the available bandwidth drops. In our experience, this design is more robust to network dropouts.
Four general-purpose nodes written in Python implement this architecture (two for the limited variant, and two for the request variant) - however, for high-performance use cases such as image and pointcloud transfer, additional special-purpose nodes written in C++ are provided. The image and pointcloud transfer nodes provide drop-in data compression to reduce bandwidth usage. Image compression is provided using the ROS image_transport library and OpenCV, while pointcloud compression is provided by ZLIB, PCL, or our own compression systems. Additional nodes are provided to resize images and optionally convert to grayscale.
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 very specific use cases.
Fair warning, this flexibility comes at a cost - these packages require thoughtful configuration for most 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. Running these nodes by hand is tricky, and we strongly advise using launch files to make your life easier. A set of launch files is provided for using this software with a RGBD camera (such as a Kinect) to illustrate their use.
Additionally, this flexibility is achieved by using a potentially large number of nodes - a general rule of thumb is that the nodes necessary for the link is 2n where n is the number of topics being sent over the relay. In general, this relay system should be used for as few topics as possible - it is a good habit in general for work over restricted datalinks to use as little data as possible - since it does impose additional processing requirements, especially when using image and pointcloud transfer.
The six tutorials for this software are ordered to first introduce you to the use of topic relays in ROS, and then provide applied examples of their use in real robotics systems. We strongly suggest following them in order to better understand the use and configuration of this software.