Eclipse Cyclone DDS

Eclipse Cyclone DDS is a very performant and robust open-source implementation of the OMG DDS specification. Cyclone DDS is developed completely in the open as an Eclipse IoT project (see eclipse-cyclone-dds) with a growing list of adopters (if you're one of them, please add your logo). It is a tier-1 middleware for the Robot Operating System ROS 2.

• What is DDS?
• Getting Started
• Performance
• Configuration

What is DDS?

DDS is the best-kept secret in distributed systems, one that has been around for much longer than most publish-subscribe messaging systems and still outclasses so many of them. DDS is used in a wide variety of systems, including air-traffic control, jet engine testing, railway control, medical systems, naval command-and-control, smart greenhouses and much more. In short, it is well-established in aerospace and defense but no longer limited to that. And yet it is easy to use!

Types are usually defined in IDL and preprocessed with the IDL compiler included in Cyclone, but our Python binding allows you to define data types on the fly:

from dataclasses import dataclass
from cyclonedds.domain import DomainParticipant
from cyclonedds.core import Qos, Policy
from cyclonedds.pub import DataWriter
from cyclonedds.sub import DataReader
from cyclonedds.topic import Topic
from cyclonedds.idl import IdlStruct
from cyclonedds.idl.annotations import key
from time import sleep
import numpy as np
try:
    from names import get_full_name
    name = get_full_name()
except:
    import os
    name = f"{os.getpid()}"

# C, C++ require using IDL, Python doesn't
@dataclass
class Chatter(IdlStruct, typename="Chatter"):
    name: str
    key("name")
    message: str
    count: int

rng = np.random.default_rng()
dp = DomainParticipant()
tp = Topic(dp, "Hello", Chatter, qos=Qos(Policy.Reliability.Reliable(0)))
dw = DataWriter(dp, tp)
dr = DataReader(dp, tp)
count = 0
while True:
    sample = Chatter(name=name, message="Hello, World!", count=count)
    count = count + 1
    print("Writing ", sample)
    dw.write(sample)
    for sample in dr.take(10):
        print("Read ", sample)
    sleep(rng.exponential())

Today DDS is also popular in robotics and autonomous vehicles because those really depend on high-throughput, low-latency control systems without introducing a single point of failure by having a message broker in the middle. Indeed, it is by far the most used and the default middleware choice in ROS 2. It is used to transfer commands, sensor data and even video and point clouds between components.

The OMG DDS specifications cover everything one needs to build systems using publish-subscribe messaging. They define a structural type system that allows automatic endianness conversion and type checking between readers and writers. This type system also supports type evolution. The interoperable networking protocol and standard C++ API make it easy to build systems that integrate multiple DDS implementations. Zero-configuration discovery is also included in the standard and supported by all implementations.

DDS actually brings more: publish-subscribe messaging is a nice abstraction over "ordinary" networking, but plain publish-subscribe doesn't affect how one thinks about systems. A very powerful architecture that truly changes the perspective on distributed systems is that of the "shared data space", in itself an old idea, and really just a distributed database. Most shared data space designs have failed miserably in real-time control systems because they provided strong consistency guarantees and sacrificed too much performance and flexibility. The eventually consistent shared data space of DDS has been very successful in helping with building systems that need to satisfy many "ilities": dependability, maintainability, extensibility, upgradeability, ... Truth be told, that's why it was invented, and publish-subscribe messaging was simply an implementation technique.

Cyclone DDS aims at full coverage of the specs and today already covers most of this. With references to the individual OMG specifications, the following is available:

• DCPS the base specification
• zero configuration discovery (if multicast works)
• publish/subscribe messaging
• configurable storage of data in subscribers
• many QoS settings - liveliness monitoring, deadlines, historical data, ...
• coverage includes the Minimum, Ownership and (partially) Content profiles
• DDS Security - providing authentication, access control and encryption
• DDS C++ API
• DDS XTypes - the structural type system (some caveats here)
• DDSI-RTPS - the interoperable network protocol

The network stack in Cyclone DDS has been around for over a decade in one form or another and has proven itself in many systems, including large, high-availability ones and systems where interoperatibility with other implementations was needed.

This repository provides the core of Cyclone DDS including its C API, the OMG C++ and the Python language bindings are in sibling repositories.

Consult the roadmap for a high-level overview of upcoming features.

Getting Started

Building Eclipse Cyclone DDS

In order to build Cyclone DDS you need a Linux, Mac or Windows 10 machine (or, with some caveats, a *BSD, QNX, OpenIndiana or a Solaris 2.6 one) with the following installed on your host:

• C compiler (most commonly GCC on Linux, Visual Studio on Windows, Xcode on macOS);
• Optionally GIT version control system;
• CMake, version 3.16 or later;
• Optionally OpenSSL, we recommend a fully patched and supported version but 1.1.1 will still work;
• Optionally Eclipse Iceoryx version 2.0 for shared memory and zero-copy support;
• Optionally Bison parser generator. A cached source is checked into the repository.

If you want to play around with the parser you will need to install the bison parser generator. On Ubuntu apt install bison should do the trick for getting it installed. On Windows, installing chocolatey and choco install winflexbison3 should get you a long way. On macOS, brew install bison is easiest.

To obtain Eclipse Cyclone DDS, do

$ git clone https://github.com/eclipse-cyclonedds/cyclonedds.git
$ cd cyclonedds
$ mkdir build

Depending on whether you want to develop applications using Cyclone DDS or contribute to it you can follow different procedures:

Build configuration

There are some configuration options specified using CMake defines in addition to the standard options like CMAKE_BUILD_TYPE:

• -DBUILD_EXAMPLES=ON: to build the included examples
• -DBUILD_TESTING=ON: to build the test suite (forces exporting all symbols from the library)
• -DBUILD_IDLC=NO: to disable building the IDL compiler (affects building examples, tests and ddsperf)
• -DBUILD_DDSPERF=NO: to disable building the ddsperf tool for performance measurement
• -DENABLE_SSL=NO: to not look for OpenSSL, remove TLS/TCP support and avoid building the plugins that implement authentication and encryption (default is AUTO to enable them if OpenSSL is found)
• -DENABLE_ICEORYX=NO: do not look for Iceoryx disable building the PSMX Iceoryx plugin (default is AUTO to enable it if Iceoryx is found)
• -DENABLE_SECURITY=NO: to not build the security interfaces and hooks in the core code, nor the plugins (one can enable security without OpenSSL present, you'll just have to find plugins elsewhere in that case)
• -DENABLE_LIFESPAN=NO: to exclude support for finite lifespans QoS
• -DENABLE_DEADLINE_MISSED=NO: to exclude support for finite deadline QoS settings
• -DENABLE_TYPELIB=NO: to exclude support for type library, requires also disabling type and topic discovery using -DENABLE_TYPE_DISCOVERY=NO and -DENABLE_TOPIC_DISCOVERY=NO
• -DENABLE_TYPE_DISCOVERY=NO: to exclude support for type discovery and checking type compatibility (effectively most of XTypes), requires also disabling topic discovery using -DENABLE_TOPIC_DISCOVERY=NO
• -DENABLE_TOPIC_DISCOVERY=NO: to exclude support for topic discovery
• -DENABLE_SOURCE_SPECIFIC_MULTICAST=NO: to disable support for source-specific multicast (disabling this and -DENABLE_IPV6=NO may be needed for QNX builds)
• -DENABLE_IPV6=NO: to disable ipv6 support (disabling this and -DENABLE_SOURCE_SPECIFIC_MULTICAST=NO may be needed for QNX builds)
• -DBUILD_IDLC_XTESTS=NO: Include a set of tests for the IDL compiler that use the C back-end to compile an idl file at (test) runtime, and use the C compiler to build a test application for the generated types, that is executed to do the actual testing (not supported on Windows)
• -DENABLE_QOS_PROVIDER=NO: to disable support for qos provider

For application developers

To build and install the required libraries needed to develop your own applications using Cyclone DDS requires a few simple steps. There are some small differences between Linux and macOS on the one hand, and Windows on the other. For Linux or macOS:

$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=<install-location> ..
$ cmake --build .

and for Windows:

$ cd build
$ cmake -G "<generator-name>" -DCMAKE_INSTALL_PREFIX=<install-location> ..
$ cmake --build .

where you should replace <install-location> by the directory under which you would like to install Cyclone DDS and <generator-name> by one of the ways CMake generators offer for generating build files. For example, "Visual Studio 15 2017 Win64" would target a 64-bit build using Visual Studio 2017.

To install it after a successful build, do:

$ cmake --build . --target install

which will copy everything to:

• <install-location>/lib
• <install-location>/bin
• <install-location>/include/ddsc
• <install-location>/share/CycloneDDS

Depending on the installation location you may need administrator privileges.

At this point you are ready to use Eclipse Cyclone DDS in your own projects.

Note that the default build type is a release build with debug information included (RelWithDebInfo), which is generally the most convenient type of build to use from applications because of a good mix between performance and still being able to debug things. If you'd rather have a Debug or pure Release build, set CMAKE_BUILD_TYPE accordingly.

Contributing to Eclipse Cyclone DDS

We very much welcome all contributions to the project, whether that is questions, examples, bug fixes, enhancements or improvements to the documentation, or anything else really. When considering contributing code, it might be good to know that build configurations for Azure pipelines are present in the repository and that there is a test suite built using a simple testing framework and CTest that can be built locally if desired. To build it, set the cmake variable BUILD_TESTING to on when configuring, e.g.:

$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON ..
$ cmake --build .
$ ctest

Documentation

The documentation is still rather limited and some parts of it are still only available in the form of text files in the docs directory. This README is usually out-of-date and the state of the documentation is slowly improving, so it definitely worth hopping over to have a look.

Building and Running the Roundtrip Example

We will show you how to build and run an example program that measures latency. The examples are built automatically when you build Cyclone DDS, so you don't need to follow these steps to be able to run the program, it is merely to illustrate the process.

$ mkdir roundtrip
$ cd roundtrip
$ cmake <install-location>/share/CycloneDDS/examples/roundtrip
$ cmake --build .

On one terminal start the application that will be responding to pings:

$ ./RoundtripPo