Async Comm
A library for asynchronous serial communication
Async Comm Library
CI Status

This project provides a C++ library that gives a simple interface for asynchronous serial communications over a serial port or UDP. It uses the Boost.Asio library under the hood, but hides from the user the details of interfacing with the ports or sockets and managing send/receive buffers.

Including in your project

There are three ways to use the async_comm library in your project:

  1. If you'll be using the library in a ROS package, install from the ROS repositories
  2. Build and install the library on your system, then use CMake's find_package() functionality
  3. Include the async_comm as a submodule in your project

With the second and third options, you will need to ensure that the Boost library is installed before proceeding:

sudo apt -y install libboost-dev libboost-system-dev

ROS install

The async_comm library is released as a third-party, non-catkin package for ROS following the guidelines in REP 136. To use the library in your ROS package, first install the library from the ROS repositories:

sudo apt install ros-<DISTRO>-async-comm

Replace <DISTRO> with your ROS distribution. The library is currently released for kinetic, lunar, and melodic.

Then, add something like the following lines to your package's CMakeLists.txt:

# ...
find_package(async_comm REQUIRED)
# ...
DEPENDS async_comm
# ...
add_executable(my_node src/my_node.cpp)
target_link_libraries(my_node ${async_comm_LIBRARIES})

Also be sure to list async_comm as a dependency in your package.xml:

<?xml version="1.0"?>
<package format="2">

System install

First, download and install the library:

git clone
cd async_comm
mkdir build && cd build/
cmake .. && make
sudo make install

Then, do something like this in your project's CMakeLists.txt:

cmake_minimum_required(VERSION 3.0.2)
find_package(async_comm REQUIRED)
add_executable(my_project src/my_project.cpp)
target_link_libraries(my_project ${async_comm_LIBRARIES})

Including as a submodule

If you don't want to go with the ROS or system install options, the next easiest way to embed the async_comm library in your project is as a Git submodule. The following instructions are for a project using Git for version control and CMake for a build system, but should serve as a starting point for other setups.

For example, to put async_comm in the lib/async_comm directory, run the following from the root of your project:

git submodule add lib/async_comm

Your CMakeLists.txt file would then look something like this:

cmake_minimum_required(VERSION 3.0.2)
add_executable(my_project src/my_project.cpp)
target_link_libraries(my_project async_comm)


There are three classes that you'll use directly as a user:

All classes have the same interface and inherit from the async_comm::Comm base class. The constructors for each class require the arguments to specify the details of the serial port, UDP or TCP socket.

The interface consists of the following functions:

More details can be found in the code API documentation. Very simple example programs are provided to illustrate the usage as described below.

One tricky part is registering the member function of a class as the receive callback. This is accomplished using std::bind. For example, if I want to register the receive function of MyClass from within the class, I would use

serial_.register_receive_callback(std::bind(&MyClass::receive, this, std::placeholders::_1, std::placeholders::_2));

where serial_ is an instance of async_comm::Serial.

Message Handlers

It is possible to implement custom handlers for the error messages and other messages produced by the library. To create a message handler, simply inherit from the MessageHandler abstract base class defined in include/async_comm/message_handler.h, and override the pure virtual functions.

Each of the user-facing classes accepts, as an optional final argument, a reference to a class that derives from MessageHandler. To use a custom message handler, simply create an instance of your handler and pass it as that optional argument. When that argument is omitted, the library uses a default message handler that prints to stdout and stderr.

A custom message handler can be especially useful, for example, when the library is used as part of a ROS node and you wish to forward the error messages to the rosconsole logging functionality. A convenience class MessageHandlerROS has been provided for this purpose. To use this handler, do something like the following:

#include <async_comm/serial.h>
#include <async_comm/util/message_handler_ros.h>
#include <ros/ros.h>
// ...
async_comm::util::MessageHandlerROS rosconsole_handler;
async_comm::Serial serial("/dev/ttyUSB0", 115200, rosconsole_handler);
// ...


There are three examples provided in the repository. The first two are very simple, while the third is more complete. To build the examples, run CMake with the -DASYNC_COMM_BUILD_EXAMPLES=ON flag.