Communications Facilities

---

Detailed Description

The RHexLib communications facilities are built with the assumption that the communications channels are unreliable, and possibly intermittent. For example, we do not use the TCP/IP messaging protocols. TCP/IP provides guaranteed messaging between processes, but the overhead and uncertainties of guaranteeing that message delivery in the face of an unreliable communications medium such as outdoor wireless ethernet networks, pose significant problems and soures of unpredictable behavior. Instead of TCP/IP, we have chosen to base our packages on the UDP (User Datagram Protocol), in which messages are not sent over ``connections'' but rather simply sent to a destination with no garauntee of receipt. We build simple, but robust, mechanisms on top of UDP to allow some garaunteed message delivery. Since we have built these mechanisms ourselves, we can more finely specify and make predictable the behavior of the message delivery in a possibly unreliable wireless ethernet environment.

The basic communications in RHexLib uses a the CommManager class. This communications manager provides interface to various UDP based protocols for sending messages between processes. On top of this package we build several convenience packages to make interprocess communications easier. The first of these uses a communications manager to set up and manage a ``database'' which can be distributed across processes. This database can be used to propagate information about the robot state when publishing from the robot to outside clients, and can be used as the central clearing house for commands when database changes come from outside clients to the robot. Another of these can be used to initiate high bandwidth logging of data, and to reliable retrieve this logged data across the network.

An important note: the RHexLib communications libraries make no provisions for communication between machines with different byte orders. In fact, you even have to be careful when sending flat C or C++ structures between processors. Either the two sides have to be compiled with the same compiler, or you have to carefully organize the structure to avoid any problems with differing methods of data alignment. For example, some compilers will pad a one byte type such as a unsigned char out to four bytes when preceding a four byte integer. Others will not. So a structure which has the elements ``unsigned char'' followed by an ``int'' is much more dangerous than the structure which has the elements ``int'' followed by an ``unsigned char''.

Although the individual components of RHexLib's communication facilities have their classes defined in a variety of header files, you will only have to include the file RHexCom.hh.

All data sent and received through the communication manager takes the form of messages, encapsulated within the Message class. There are two paradigms for sending and receiving messages in RHexLib: Mailboxes and Streams. The classes Mailbox and Mailer can be used for the former, whereas the classes StreamSource and StreamSink are designed for the latter form of communications. Message streams allow users to create stream sources which send messages with guarantees on their delivery while still maintaining fine grained control over the delivery attempts. Unlike mailboxes, stream sinks (the destination for stream messages) maintain a queue of incoming messages rather than simply the last message. The following sections provide illustrative examples for all these facilities:

• Examples and caveats on using messages
• Example on using the Mailer class
• Example on using the Mailbox class
• Example on using the StreamSource class
• Example on using the StreamSink class

Remote managers

When you create a mailer or a stream source you pass in a machine and a UDP port number. Internally, this creates a reference to the remote communications manager which is maintained by an instance of the class RemoteManager. In addition, for every instance of RemoteManager has a record of the last time communications was received from that remote communications manager and what that remote manager's identifier currently is.

Your communications manager does not merely maintain a record of the last contact time in a RemoteManager, but for every RemoteManager it maintains, if the contact time is older than a certain threshold, one of the communication manager's sub-threads will attempt to ``ping'' the remote communications manager to elicit a response. Thus, a RemoteManager can act as the ``heartbeat'' counter even for a communications manager which from the user's point of view should only be receiving information.

Normally, RemoteManager's will be instantiated in the course of creating mailers and stream sources, but you can also use CommManager::openRemote to directly add a host and port to the list of remote managers to be pinged.

• Example on how to set up a ping of a remote communications manager

Compounds
class	CommManager
	Manager class for mailbox and stream based network communications. More...
class	CommPortal
	Virtual abstract class for a messager modality. More...
class	FileCommMonitor
	Monitors a set of file descriptors from file communication portals for messages. More...
class	FileCommPortal
	Helper class for messagers which use file descriptors. More...
class	Mailbox
	Class for receiving messages from remote mailers. More...
class	Mailer
	Class for sending messages to a mailbox. More...
class	Message
	Class to represent all messages sent and received by mailboxes and streams. More...
class	Messager
	Superclass for both Mailer and StreamSource classes. More...
class	NetCommPortal
	Concrete class for a network messaging. More...
class	NetRemoteManager
	Class for a remote manager connected via the UDP socket. More...
class	RemoteManager
	Class to keep track of a remote communications manager. More...
class	SerialCommPortal
	Concrete class for a network messaging. More...
class	SerialRemoteManager
	Class for a remote manager connected via a serial line. More...
class	StreamSink
	Class for receiving messages coming from stream sources. More...
class	StreamSource
	Class for sending messages to a remote stream sink. More...

---

RHexLib Reference Documentation