ros_acomms Overview#

ros_acomms enables transport of ROS messages and other data across low-throughput and high-latency underwater acoustic links. Messages are efficiently marshalled using user-provided configuration data, if available, or automatically via message introspection. A modular set of modem drivers, media-access- control engines, and message queues transport messages from one system to another via a modem. It also includes an acoustic link simulator that uses a ray- tracing model to estimate link performance and latency. While it targets the WHOI Micromodem family of acoustic modems, the modular modem driver implementation has been leveraged to support low-throughput Iridium satellite links and other acoustic modems. It has been tested and used operationally at sea for remote redirection of autonomous underwater vehicles while providing operators with near real time vehicle telemetry and sensor data.

If you use this package in any of your published work, please cite the associated paper:

  1. Gallimore et al., “ROS Message Transport over Underwater Acoustic Links with ros_acomms,” in 2022 IEEE/OES Autonomous Underwater Vehicles Symposium (AUV), Sep. 2022, pp. 1-6. doi: 10.1109/AUV53081.2022.9965848.

Here is a preprint of the paper you can view or download. The published version is on IEEE Xplore.

Status of ros_acomms#

ros_acomms is stable enough to be used at sea and has seen significant deployment time (at least thousands of hours of operation).

As always, you should test your configuration thoroughly before deployment and have suitable backup plans in place.

Note that the documentation is much more of a work-in-progress than the code is.

The code is CI tested, including tests that interface with actual modem hardware.

Versioning#

ros_acomms uses Semantic Versioning, with version numbers in the form major.minor.patch.

We take this to mean that:

  • Backward compatibility will only be broken with a major version. This includes both API changes and also breaking changes to requirements and dependencies.

  • New features added in a backward-compatible way increment the minor version.

  • Bugfixes and documentation changes increment the patch version.

ROS Message Transport Overview#

ros_acomms provides a complete system for transporting messages across the acoustic link.

Data Flow Overview

Data Flow Overview#

To transmit a ROS message:

  1. The user publishes ROS message on a topic

  2. The Message Queue Node subscribes to that topic.

  3. When a new ROS message is received, the Message Queue Node uses a Message Codec to convert the data in the message into a compact bit-packet representation by using Field Codecs to encode each message field, including nested ROS messages.

  4. The Media Access Controller (for now, the TDMA MAC) queries the Message Queue Node to get the highest priority message for transmit

  5. The Message Queue Node identifies the highest priority message, and then uses the appropriate Packet Codec to pack as many messages as will fit into one modem Packet for transport.

  6. The Media Access Controller queues the Packet for transmit on the Acomms Driver Node, which interfaces to the modem to actually transmit the packet

On the receive side:

  1. A packet is received by the modem.

  2. The Acomms Driver Node handles the incoming packet and publishes it as a ReceivedPacket

  3. The Packet Dispatch Node evaluates metadata on the packet (the modem SRC, header bytes) and determines which Packet Codec to use to decode the packet.

  4. The Packet Codec uses calls one or more Message Codecs to decode the packed bits into a ROS message

  5. The Packet Dispatch Node publishes the decoded ROS message on a user-specified topic.

When using simulation, the Acomms Driver Node is replaced by the Modem Sim Node, but the rest of the flow is the same.

There is also a more flexible interface to queue messages from a system that manages its own message queues: Dynamic Queues, where the message queue node queries a service for messages on-demand when the MAC node indicates that it is ready to send data.

While ros_acomms is targeted at the WHOI Micromodem, it is possible to use it with other modems. ros_iridium is an example that provides a modem driver for Iridium RUDICS links.

Message Fragmentation and File Transfer#

ros_acomms used to implement message fragmentation and reliable transport with positive acknowledgement and retry logic. However, those capabilities have been deprecated and moved to ros_acomms_net, which provides additional features.

Files can be transferred across an acoustic link using ros_acomms by packing them in a uint8[] field of a ROS message. Python, C, JPG, PNG, or any other types of files can be parsed using Python and then packed into a message that can be sent through ros_acomms. However, files (messages) that are too large to fit in a single modem packet will need to be fragmented, so using ros_acomms_net is recommended in these cases.