Repository Summary
Checkout URI | https://github.com/eclipse-cyclonedds/cyclonedds.git |
VCS Type | git |
VCS Version | releases/0.10.x |
Last Updated | 2024-05-17 |
Dev Status | MAINTAINED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Packages
Name | Version |
---|---|
cyclonedds | 0.10.5 |
README
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?
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, preferably version 1.1;
- 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 andddsperf
) -
-DBUILD_DDSPERF=NO
: to disable building theddsperf
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 isAUTO
to enable them if OpenSSL is found) -
-DENABLE_SHM=NO
: to not look for Iceoryx and disabled shared memory support (default isAUTO
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_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)
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:
$ ./RoundtripPong
On another terminal, start the application that will be sending the pings:
$ ./RoundtripPing 0 0 0
# payloadSize: 0 | numSamples: 0 | timeOut: 0
# Waiting for startup jitter to stabilise
# Warm up complete.
# Latency measurements (in us)
# Latency [us] Write-access time [us] Read-access time [us]
# Seconds Count median min 99% max Count median min Count median min
1 28065 17 16 23 87 28065 8 6 28065 1 0
2 28115 17 16 23 46 28115 8 6 28115 1 0
3 28381 17 16 22 46 28381 8 6 28381 1 0
4 27928 17 16 24 127 27928 8 6 27928 1 0
5 28427 17 16 20 47 28427 8 6 28427 1 0
6 27685 17 16 26 51 27685 8 6 27685 1 0
7 28391 17 16 23 47 28391 8 6 28391 1 0
8 27938 17 16 24 63 27938 8 6 27938 1 0
9 28242 17 16 24 132 28242 8 6 28242 1 0
10 28075 17 16 23 46 28075 8 6 28075 1 0
The numbers above were measured on Mac running a 4.2 GHz Intel Core i7 on December 12th 2018. From these numbers you can see how the roundtrip is very stable and the minimal latency is now down to 17 micro-seconds (used to be 25 micro-seconds) on this HW.
Performance
Reliable message throughput is over 1MS/s for very small samples and is roughly 90% of GbE with 100 byte samples, and latency is about 30us when measured using ddsperf between two Intel(R) Xeon(R) CPU E3-1270 V2 @ 3.50GHz (that’s 2012 hardware …) running Ubuntu 16.04, with the executables built on Ubuntu 18.04 using gcc 7.4.0 for a default (i.e., “RelWithDebInfo”) build.
This is with the subscriber in listener mode, using asynchronous delivery for the throughput test. The configuration is a marginally tweaked out-of-the-box configuration: an increased maximum message size and fragment size, and an increased high-water mark for the reliability window on the writer side. For details, see the scripts directory, the environment details and the throughput and latency data underlying the graphs. These also include CPU usage (throughput and latency) and memory usage.
Run-time configuration
The out-of-the-box configuration should usually be fine, but there are a great many options that can be tweaked by creating an XML file with the desired settings and defining the CYCLONEDDS_URI
to point to it.
E.g. (on Linux):
$ cat cyclonedds.xml
<?xml version="1.0" encoding="UTF-8" ?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
<Domain Id="any">
<General>
<Interfaces>
<NetworkInterface autodetermine="true" priority="default" multicast="default" />
</Interfaces>
<AllowMulticast>default</AllowMulticast>
<MaxMessageSize>65500B</MaxMessageSize>
</General>
<Discovery>
<EnableTopicDiscoveryEndpoints>true</EnableTopicDiscoveryEndpoints>
</Discovery>
<Internal>
<Watermarks>
<WhcHigh>500kB</WhcHigh>
</Watermarks>
</Internal>
<Tracing>
<Verbosity>config</Verbosity>
<OutputFile>cdds.log.${CYCLONEDDS_PID}</OutputFile>
</Tracing>
</Domain>
</CycloneDDS>
$ export CYCLONEDDS_URI=file://$PWD/cyclonedds.xml
(on Windows, one would have to use set CYCLONEDDS_URI=file://...
instead.)
This example shows a few things:
-
Interfaces
can be used to override the interfaces selected by default. Members are-
NetworkInterface[@autodetermine]
tells Cyclone DDS to autoselect the interface it deems best. -
NetworkInterface[@name]
specifies the name of an interface to select (not shown above, alternative for autodetermine). -
NetworkInterface[@ip]
specifies the ipv4/ipv6 address of an interface to select (not shown above, alternative for autodetermine). -
NetworkInterface[@multicast]
specifies whether multicast should be used on this interface. The default value ‘default’ means Cyclone DDS will check the OS reported flags of the interface and enable multicast if it is supported. Use ‘true’ to ignore what the OS reports and enable it anyway and ‘false’ to always disable multicast on this interface. -
NetworkInterface[@priority]
specifies the priority of an interface. The default value (default
) means priority0
for normal interfaces and2
for loopback interfaces.
-
-
AllowMulticast
configures the circumstances under which multicast will be used. If the selected interface doesn’t support it, it obviously won’t be used (false
); but if it does support it, the type of the network adapter determines the default value. For a wired network, it will use multicast for initial discovery as well as for data when there are multiple peers that the data needs to go to (true
). On a WiFi network it will use it only for initial discovery (spdp
), because multicast on WiFi is very unreliable. -
EnableTopicDiscoveryEndpoints
turns on topic discovery (assuming it is enabled at compile time), it is disabled by default because it isn’t used in many system and comes with a significant amount of overhead in discovery traffic. -
Verbosity
allows control over the tracing, “config” dumps the configuration to the trace output (which defaults to “cyclonedds.log”, but here the process id is appended). Which interface is used, what multicast settings are used, etc., is all in the trace. Setting the verbosity to “finest” gives way more output on the inner workings, and there are various other levels as well. -
MaxMessageSize
controls the maximum size of the RTPS messages (basically the size of the UDP payload). Large values such as these typically improve performance over the (current) default values on a loopback interface. -
WhcHigh
determines when the sender will wait for acknowledgements from the readers because it has buffered too much unacknowledged data. There is some auto-tuning, the (current) default value is a bit small to get really high throughput.
Background information on configuring Cyclone DDS can be found here and a list of settings is available.
Trademarks
- “Eclipse Cyclone DDS”, “Cyclone DDS”, “Eclipse Iceoryx” and “Iceoryx” are trademarks of the Eclipse Foundation.
- “DDS” is a trademark of the Object Management Group, Inc.
- “ROS” is a trademark of Open Source Robotics Foundation, Inc.
CONTRIBUTING
Contributing to Eclipse Cyclone DDS
Thanks for your interest in this project.
Project description
Eclipse Cyclone DDS is an implementation of the OMG Data Distribution Service (DDS) specification (see http://www.omg.org/spec/DDS/ ) and the related specifications for interoperability (see http://www.omg.org/spec/DDSI-RTPS/ )
- https://projects.eclipse.org/projects/iot.cyclonedds
Developer resources
Information regarding source code management, builds, coding standards, and more.
- https://projects.eclipse.org/projects/iot.cyclonedds/developer
The project maintains the following source code repositories
- https://github.com/eclipse/cyclonedds
Eclipse Contributor Agreement
Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA).
- http://www.eclipse.org/legal/ECA.php
Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.
For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit
Contact
Contact the project developers via the project’s “dev” list.
- https://accounts.eclipse.org/mailing-list/cyclonedds-dev
Repository Summary
Checkout URI | https://github.com/eclipse-cyclonedds/cyclonedds.git |
VCS Type | git |
VCS Version | releases/0.10.x |
Last Updated | 2024-05-17 |
Dev Status | MAINTAINED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Packages
Name | Version |
---|---|
cyclonedds | 0.10.5 |
README
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?
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, preferably version 1.1;
- 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 andddsperf
) -
-DBUILD_DDSPERF=NO
: to disable building theddsperf
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 isAUTO
to enable them if OpenSSL is found) -
-DENABLE_SHM=NO
: to not look for Iceoryx and disabled shared memory support (default isAUTO
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_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)
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:
$ ./RoundtripPong
On another terminal, start the application that will be sending the pings:
$ ./RoundtripPing 0 0 0
# payloadSize: 0 | numSamples: 0 | timeOut: 0
# Waiting for startup jitter to stabilise
# Warm up complete.
# Latency measurements (in us)
# Latency [us] Write-access time [us] Read-access time [us]
# Seconds Count median min 99% max Count median min Count median min
1 28065 17 16 23 87 28065 8 6 28065 1 0
2 28115 17 16 23 46 28115 8 6 28115 1 0
3 28381 17 16 22 46 28381 8 6 28381 1 0
4 27928 17 16 24 127 27928 8 6 27928 1 0
5 28427 17 16 20 47 28427 8 6 28427 1 0
6 27685 17 16 26 51 27685 8 6 27685 1 0
7 28391 17 16 23 47 28391 8 6 28391 1 0
8 27938 17 16 24 63 27938 8 6 27938 1 0
9 28242 17 16 24 132 28242 8 6 28242 1 0
10 28075 17 16 23 46 28075 8 6 28075 1 0
The numbers above were measured on Mac running a 4.2 GHz Intel Core i7 on December 12th 2018. From these numbers you can see how the roundtrip is very stable and the minimal latency is now down to 17 micro-seconds (used to be 25 micro-seconds) on this HW.
Performance
Reliable message throughput is over 1MS/s for very small samples and is roughly 90% of GbE with 100 byte samples, and latency is about 30us when measured using ddsperf between two Intel(R) Xeon(R) CPU E3-1270 V2 @ 3.50GHz (that’s 2012 hardware …) running Ubuntu 16.04, with the executables built on Ubuntu 18.04 using gcc 7.4.0 for a default (i.e., “RelWithDebInfo”) build.
This is with the subscriber in listener mode, using asynchronous delivery for the throughput test. The configuration is a marginally tweaked out-of-the-box configuration: an increased maximum message size and fragment size, and an increased high-water mark for the reliability window on the writer side. For details, see the scripts directory, the environment details and the throughput and latency data underlying the graphs. These also include CPU usage (throughput and latency) and memory usage.
Run-time configuration
The out-of-the-box configuration should usually be fine, but there are a great many options that can be tweaked by creating an XML file with the desired settings and defining the CYCLONEDDS_URI
to point to it.
E.g. (on Linux):
$ cat cyclonedds.xml
<?xml version="1.0" encoding="UTF-8" ?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
<Domain Id="any">
<General>
<Interfaces>
<NetworkInterface autodetermine="true" priority="default" multicast="default" />
</Interfaces>
<AllowMulticast>default</AllowMulticast>
<MaxMessageSize>65500B</MaxMessageSize>
</General>
<Discovery>
<EnableTopicDiscoveryEndpoints>true</EnableTopicDiscoveryEndpoints>
</Discovery>
<Internal>
<Watermarks>
<WhcHigh>500kB</WhcHigh>
</Watermarks>
</Internal>
<Tracing>
<Verbosity>config</Verbosity>
<OutputFile>cdds.log.${CYCLONEDDS_PID}</OutputFile>
</Tracing>
</Domain>
</CycloneDDS>
$ export CYCLONEDDS_URI=file://$PWD/cyclonedds.xml
(on Windows, one would have to use set CYCLONEDDS_URI=file://...
instead.)
This example shows a few things:
-
Interfaces
can be used to override the interfaces selected by default. Members are-
NetworkInterface[@autodetermine]
tells Cyclone DDS to autoselect the interface it deems best. -
NetworkInterface[@name]
specifies the name of an interface to select (not shown above, alternative for autodetermine). -
NetworkInterface[@ip]
specifies the ipv4/ipv6 address of an interface to select (not shown above, alternative for autodetermine). -
NetworkInterface[@multicast]
specifies whether multicast should be used on this interface. The default value ‘default’ means Cyclone DDS will check the OS reported flags of the interface and enable multicast if it is supported. Use ‘true’ to ignore what the OS reports and enable it anyway and ‘false’ to always disable multicast on this interface. -
NetworkInterface[@priority]
specifies the priority of an interface. The default value (default
) means priority0
for normal interfaces and2
for loopback interfaces.
-
-
AllowMulticast
configures the circumstances under which multicast will be used. If the selected interface doesn’t support it, it obviously won’t be used (false
); but if it does support it, the type of the network adapter determines the default value. For a wired network, it will use multicast for initial discovery as well as for data when there are multiple peers that the data needs to go to (true
). On a WiFi network it will use it only for initial discovery (spdp
), because multicast on WiFi is very unreliable. -
EnableTopicDiscoveryEndpoints
turns on topic discovery (assuming it is enabled at compile time), it is disabled by default because it isn’t used in many system and comes with a significant amount of overhead in discovery traffic. -
Verbosity
allows control over the tracing, “config” dumps the configuration to the trace output (which defaults to “cyclonedds.log”, but here the process id is appended). Which interface is used, what multicast settings are used, etc., is all in the trace. Setting the verbosity to “finest” gives way more output on the inner workings, and there are various other levels as well. -
MaxMessageSize
controls the maximum size of the RTPS messages (basically the size of the UDP payload). Large values such as these typically improve performance over the (current) default values on a loopback interface. -
WhcHigh
determines when the sender will wait for acknowledgements from the readers because it has buffered too much unacknowledged data. There is some auto-tuning, the (current) default value is a bit small to get really high throughput.
Background information on configuring Cyclone DDS can be found here and a list of settings is available.
Trademarks
- “Eclipse Cyclone DDS”, “Cyclone DDS”, “Eclipse Iceoryx” and “Iceoryx” are trademarks of the Eclipse Foundation.
- “DDS” is a trademark of the Object Management Group, Inc.
- “ROS” is a trademark of Open Source Robotics Foundation, Inc.
CONTRIBUTING
Contributing to Eclipse Cyclone DDS
Thanks for your interest in this project.
Project description
Eclipse Cyclone DDS is an implementation of the OMG Data Distribution Service (DDS) specification (see http://www.omg.org/spec/DDS/ ) and the related specifications for interoperability (see http://www.omg.org/spec/DDSI-RTPS/ )
- https://projects.eclipse.org/projects/iot.cyclonedds
Developer resources
Information regarding source code management, builds, coding standards, and more.
- https://projects.eclipse.org/projects/iot.cyclonedds/developer
The project maintains the following source code repositories
- https://github.com/eclipse/cyclonedds
Eclipse Contributor Agreement
Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA).
- http://www.eclipse.org/legal/ECA.php
Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.
For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit
Contact
Contact the project developers via the project’s “dev” list.
- https://accounts.eclipse.org/mailing-list/cyclonedds-dev
Repository Summary
Checkout URI | https://github.com/eclipse-cyclonedds/cyclonedds.git |
VCS Type | git |
VCS Version | releases/0.10.x |
Last Updated | 2024-05-17 |
Dev Status | MAINTAINED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Packages
Name | Version |
---|---|
cyclonedds | 0.10.5 |
README
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?
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, preferably version 1.1;
- 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 andddsperf
) -
-DBUILD_DDSPERF=NO
: to disable building theddsperf
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 isAUTO
to enable them if OpenSSL is found) -
-DENABLE_SHM=NO
: to not look for Iceoryx and disabled shared memory support (default isAUTO
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_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)
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:
$ ./RoundtripPong
On another terminal, start the application that will be sending the pings:
$ ./RoundtripPing 0 0 0
# payloadSize: 0 | numSamples: 0 | timeOut: 0
# Waiting for startup jitter to stabilise
# Warm up complete.
# Latency measurements (in us)
# Latency [us] Write-access time [us] Read-access time [us]
# Seconds Count median min 99% max Count median min Count median min
1 28065 17 16 23 87 28065 8 6 28065 1 0
2 28115 17 16 23 46 28115 8 6 28115 1 0
3 28381 17 16 22 46 28381 8 6 28381 1 0
4 27928 17 16 24 127 27928 8 6 27928 1 0
5 28427 17 16 20 47 28427 8 6 28427 1 0
6 27685 17 16 26 51 27685 8 6 27685 1 0
7 28391 17 16 23 47 28391 8 6 28391 1 0
8 27938 17 16 24 63 27938 8 6 27938 1 0
9 28242 17 16 24 132 28242 8 6 28242 1 0
10 28075 17 16 23 46 28075 8 6 28075 1 0
The numbers above were measured on Mac running a 4.2 GHz Intel Core i7 on December 12th 2018. From these numbers you can see how the roundtrip is very stable and the minimal latency is now down to 17 micro-seconds (used to be 25 micro-seconds) on this HW.
Performance
Reliable message throughput is over 1MS/s for very small samples and is roughly 90% of GbE with 100 byte samples, and latency is about 30us when measured using ddsperf between two Intel(R) Xeon(R) CPU E3-1270 V2 @ 3.50GHz (that’s 2012 hardware …) running Ubuntu 16.04, with the executables built on Ubuntu 18.04 using gcc 7.4.0 for a default (i.e., “RelWithDebInfo”) build.
This is with the subscriber in listener mode, using asynchronous delivery for the throughput test. The configuration is a marginally tweaked out-of-the-box configuration: an increased maximum message size and fragment size, and an increased high-water mark for the reliability window on the writer side. For details, see the scripts directory, the environment details and the throughput and latency data underlying the graphs. These also include CPU usage (throughput and latency) and memory usage.
Run-time configuration
The out-of-the-box configuration should usually be fine, but there are a great many options that can be tweaked by creating an XML file with the desired settings and defining the CYCLONEDDS_URI
to point to it.
E.g. (on Linux):
$ cat cyclonedds.xml
<?xml version="1.0" encoding="UTF-8" ?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
<Domain Id="any">
<General>
<Interfaces>
<NetworkInterface autodetermine="true" priority="default" multicast="default" />
</Interfaces>
<AllowMulticast>default</AllowMulticast>
<MaxMessageSize>65500B</MaxMessageSize>
</General>
<Discovery>
<EnableTopicDiscoveryEndpoints>true</EnableTopicDiscoveryEndpoints>
</Discovery>
<Internal>
<Watermarks>
<WhcHigh>500kB</WhcHigh>
</Watermarks>
</Internal>
<Tracing>
<Verbosity>config</Verbosity>
<OutputFile>cdds.log.${CYCLONEDDS_PID}</OutputFile>
</Tracing>
</Domain>
</CycloneDDS>
$ export CYCLONEDDS_URI=file://$PWD/cyclonedds.xml
(on Windows, one would have to use set CYCLONEDDS_URI=file://...
instead.)
This example shows a few things:
-
Interfaces
can be used to override the interfaces selected by default. Members are-
NetworkInterface[@autodetermine]
tells Cyclone DDS to autoselect the interface it deems best. -
NetworkInterface[@name]
specifies the name of an interface to select (not shown above, alternative for autodetermine). -
NetworkInterface[@ip]
specifies the ipv4/ipv6 address of an interface to select (not shown above, alternative for autodetermine). -
NetworkInterface[@multicast]
specifies whether multicast should be used on this interface. The default value ‘default’ means Cyclone DDS will check the OS reported flags of the interface and enable multicast if it is supported. Use ‘true’ to ignore what the OS reports and enable it anyway and ‘false’ to always disable multicast on this interface. -
NetworkInterface[@priority]
specifies the priority of an interface. The default value (default
) means priority0
for normal interfaces and2
for loopback interfaces.
-
-
AllowMulticast
configures the circumstances under which multicast will be used. If the selected interface doesn’t support it, it obviously won’t be used (false
); but if it does support it, the type of the network adapter determines the default value. For a wired network, it will use multicast for initial discovery as well as for data when there are multiple peers that the data needs to go to (true
). On a WiFi network it will use it only for initial discovery (spdp
), because multicast on WiFi is very unreliable. -
EnableTopicDiscoveryEndpoints
turns on topic discovery (assuming it is enabled at compile time), it is disabled by default because it isn’t used in many system and comes with a significant amount of overhead in discovery traffic. -
Verbosity
allows control over the tracing, “config” dumps the configuration to the trace output (which defaults to “cyclonedds.log”, but here the process id is appended). Which interface is used, what multicast settings are used, etc., is all in the trace. Setting the verbosity to “finest” gives way more output on the inner workings, and there are various other levels as well. -
MaxMessageSize
controls the maximum size of the RTPS messages (basically the size of the UDP payload). Large values such as these typically improve performance over the (current) default values on a loopback interface. -
WhcHigh
determines when the sender will wait for acknowledgements from the readers because it has buffered too much unacknowledged data. There is some auto-tuning, the (current) default value is a bit small to get really high throughput.
Background information on configuring Cyclone DDS can be found here and a list of settings is available.
Trademarks
- “Eclipse Cyclone DDS”, “Cyclone DDS”, “Eclipse Iceoryx” and “Iceoryx” are trademarks of the Eclipse Foundation.
- “DDS” is a trademark of the Object Management Group, Inc.
- “ROS” is a trademark of Open Source Robotics Foundation, Inc.
CONTRIBUTING
Contributing to Eclipse Cyclone DDS
Thanks for your interest in this project.
Project description
Eclipse Cyclone DDS is an implementation of the OMG Data Distribution Service (DDS) specification (see http://www.omg.org/spec/DDS/ ) and the related specifications for interoperability (see http://www.omg.org/spec/DDSI-RTPS/ )
- https://projects.eclipse.org/projects/iot.cyclonedds
Developer resources
Information regarding source code management, builds, coding standards, and more.
- https://projects.eclipse.org/projects/iot.cyclonedds/developer
The project maintains the following source code repositories
- https://github.com/eclipse/cyclonedds
Eclipse Contributor Agreement
Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA).
- http://www.eclipse.org/legal/ECA.php
Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.
For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit
Contact
Contact the project developers via the project’s “dev” list.
- https://accounts.eclipse.org/mailing-list/cyclonedds-dev
Repository Summary
Checkout URI | https://github.com/eclipse-cyclonedds/cyclonedds.git |
VCS Type | git |
VCS Version | releases/0.10.x |
Last Updated | 2024-05-17 |
Dev Status | MAINTAINED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Packages
Name | Version |
---|---|
cyclonedds | 0.10.5 |
README
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?
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, preferably version 1.1;
- 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 andddsperf
) -
-DBUILD_DDSPERF=NO
: to disable building theddsperf
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 isAUTO
to enable them if OpenSSL is found) -
-DENABLE_SHM=NO
: to not look for Iceoryx and disabled shared memory support (default isAUTO
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_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)
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:
$ ./RoundtripPong
On another terminal, start the application that will be sending the pings:
$ ./RoundtripPing 0 0 0
# payloadSize: 0 | numSamples: 0 | timeOut: 0
# Waiting for startup jitter to stabilise
# Warm up complete.
# Latency measurements (in us)
# Latency [us] Write-access time [us] Read-access time [us]
# Seconds Count median min 99% max Count median min Count median min
1 28065 17 16 23 87 28065 8 6 28065 1 0
2 28115 17 16 23 46 28115 8 6 28115 1 0
3 28381 17 16 22 46 28381 8 6 28381 1 0
4 27928 17 16 24 127 27928 8 6 27928 1 0
5 28427 17 16 20 47 28427 8 6 28427 1 0
6 27685 17 16 26 51 27685 8 6 27685 1 0
7 28391 17 16 23 47 28391 8 6 28391 1 0
8 27938 17 16 24 63 27938 8 6 27938 1 0
9 28242 17 16 24 132 28242 8 6 28242 1 0
10 28075 17 16 23 46 28075 8 6 28075 1 0
The numbers above were measured on Mac running a 4.2 GHz Intel Core i7 on December 12th 2018. From these numbers you can see how the roundtrip is very stable and the minimal latency is now down to 17 micro-seconds (used to be 25 micro-seconds) on this HW.
Performance
Reliable message throughput is over 1MS/s for very small samples and is roughly 90% of GbE with 100 byte samples, and latency is about 30us when measured using ddsperf between two Intel(R) Xeon(R) CPU E3-1270 V2 @ 3.50GHz (that’s 2012 hardware …) running Ubuntu 16.04, with the executables built on Ubuntu 18.04 using gcc 7.4.0 for a default (i.e., “RelWithDebInfo”) build.
This is with the subscriber in listener mode, using asynchronous delivery for the throughput test. The configuration is a marginally tweaked out-of-the-box configuration: an increased maximum message size and fragment size, and an increased high-water mark for the reliability window on the writer side. For details, see the scripts directory, the environment details and the throughput and latency data underlying the graphs. These also include CPU usage (throughput and latency) and memory usage.
Run-time configuration
The out-of-the-box configuration should usually be fine, but there are a great many options that can be tweaked by creating an XML file with the desired settings and defining the CYCLONEDDS_URI
to point to it.
E.g. (on Linux):
$ cat cyclonedds.xml
<?xml version="1.0" encoding="UTF-8" ?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
<Domain Id="any">
<General>
<Interfaces>
<NetworkInterface autodetermine="true" priority="default" multicast="default" />
</Interfaces>
<AllowMulticast>default</AllowMulticast>
<MaxMessageSize>65500B</MaxMessageSize>
</General>
<Discovery>
<EnableTopicDiscoveryEndpoints>true</EnableTopicDiscoveryEndpoints>
</Discovery>
<Internal>
<Watermarks>
<WhcHigh>500kB</WhcHigh>
</Watermarks>
</Internal>
<Tracing>
<Verbosity>config</Verbosity>
<OutputFile>cdds.log.${CYCLONEDDS_PID}</OutputFile>
</Tracing>
</Domain>
</CycloneDDS>
$ export CYCLONEDDS_URI=file://$PWD/cyclonedds.xml
(on Windows, one would have to use set CYCLONEDDS_URI=file://...
instead.)
This example shows a few things:
-
Interfaces
can be used to override the interfaces selected by default. Members are-
NetworkInterface[@autodetermine]
tells Cyclone DDS to autoselect the interface it deems best. -
NetworkInterface[@name]
specifies the name of an interface to select (not shown above, alternative for autodetermine). -
NetworkInterface[@ip]
specifies the ipv4/ipv6 address of an interface to select (not shown above, alternative for autodetermine). -
NetworkInterface[@multicast]
specifies whether multicast should be used on this interface. The default value ‘default’ means Cyclone DDS will check the OS reported flags of the interface and enable multicast if it is supported. Use ‘true’ to ignore what the OS reports and enable it anyway and ‘false’ to always disable multicast on this interface. -
NetworkInterface[@priority]
specifies the priority of an interface. The default value (default
) means priority0
for normal interfaces and2
for loopback interfaces.
-
-
AllowMulticast
configures the circumstances under which multicast will be used. If the selected interface doesn’t support it, it obviously won’t be used (false
); but if it does support it, the type of the network adapter determines the default value. For a wired network, it will use multicast for initial discovery as well as for data when there are multiple peers that the data needs to go to (true
). On a WiFi network it will use it only for initial discovery (spdp
), because multicast on WiFi is very unreliable. -
EnableTopicDiscoveryEndpoints
turns on topic discovery (assuming it is enabled at compile time), it is disabled by default because it isn’t used in many system and comes with a significant amount of overhead in discovery traffic. -
Verbosity
allows control over the tracing, “config” dumps the configuration to the trace output (which defaults to “cyclonedds.log”, but here the process id is appended). Which interface is used, what multicast settings are used, etc., is all in the trace. Setting the verbosity to “finest” gives way more output on the inner workings, and there are various other levels as well. -
MaxMessageSize
controls the maximum size of the RTPS messages (basically the size of the UDP payload). Large values such as these typically improve performance over the (current) default values on a loopback interface. -
WhcHigh
determines when the sender will wait for acknowledgements from the readers because it has buffered too much unacknowledged data. There is some auto-tuning, the (current) default value is a bit small to get really high throughput.
Background information on configuring Cyclone DDS can be found here and a list of settings is available.
Trademarks
- “Eclipse Cyclone DDS”, “Cyclone DDS”, “Eclipse Iceoryx” and “Iceoryx” are trademarks of the Eclipse Foundation.
- “DDS” is a trademark of the Object Management Group, Inc.
- “ROS” is a trademark of Open Source Robotics Foundation, Inc.
CONTRIBUTING
Contributing to Eclipse Cyclone DDS
Thanks for your interest in this project.
Project description
Eclipse Cyclone DDS is an implementation of the OMG Data Distribution Service (DDS) specification (see http://www.omg.org/spec/DDS/ ) and the related specifications for interoperability (see http://www.omg.org/spec/DDSI-RTPS/ )
- https://projects.eclipse.org/projects/iot.cyclonedds
Developer resources
Information regarding source code management, builds, coding standards, and more.
- https://projects.eclipse.org/projects/iot.cyclonedds/developer
The project maintains the following source code repositories
- https://github.com/eclipse/cyclonedds
Eclipse Contributor Agreement
Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA).
- http://www.eclipse.org/legal/ECA.php
Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.
For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit
Contact
Contact the project developers via the project’s “dev” list.
- https://accounts.eclipse.org/mailing-list/cyclonedds-dev
Repository Summary
Checkout URI | https://github.com/eclipse-cyclonedds/cyclonedds.git |
VCS Type | git |
VCS Version | releases/0.5.x |
Last Updated | 2020-03-12 |
Dev Status | MAINTAINED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Packages
Name | Version |
---|---|
cyclonedds | 0.5.1 |
README
Eclipse Cyclone DDS
Eclipse Cyclone DDS is a very performant and robust open-source DDS implementation. Cyclone DDS is developed completely in the open as an Eclipse IoT project (see eclipse-cyclone-dds).
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, an OpenIndiana one 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);
- GIT version control system;
- CMake, version 3.7 or later;
-
OpenSSL, preferably version 1.1 or later if you want to use TLS over
TCP. You can explicitly disable it by setting
ENABLE_SSL=NO
, which is very useful for reducing the footprint or when the FindOpenSSL CMake script gives you trouble; - Java JDK, version 8 or later, e.g., OpenJDK;
- Apache Maven, version 3.5 or later.
On Ubuntu apt install maven default-jdk
should do the trick for getting Java and Maven
installed, and the rest should already be there. On Windows, installing chocolatey and choco
install git cmake openjdk maven
should get you a long way. On macOS, brew install maven cmake
and downloading and installing the JDK is easiest.
The Java-based components are the preprocessor and a configurator tool. The run-time
libraries are pure C code, so there is no need to have Java available on “target”
machines. If desired, it is possible to do a build without Java or Maven installed by
defining BUILD_IDLC=NO
, but that effectively only gets you the core library. For the
current ROS2 RMW layer, that is sufficient.
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
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 Travis CI and AppVeyor are
present in the repository and that there is a test suite using CTest and CUnit 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
Such a build requires the presence of CUnit. You can install this yourself, or you can choose to instead rely on the Conan packaging system that the CI build infrastructure also uses. In that case, install Conan and do:
$ conan install .. --build missing
in the build directory prior to running cmake.
The CUnit Conan package is hosted in the Bincrafters Bintray repository. In case this repository was not added to your Conan remotes list yet (and the above mentioned install command failed because it could not find the CUnit package), you can add the Bintray repository by:
$ conan remote add <REMOTE> https://api.bintray.com/conan/bincrafters/public-conan
Replace <REMOTE>
with a name that identifies the repository (e.g. bincrafters
).
For Windows, depending on the generator, you might also need to add switches to select the architecture
and build type, e.g., conan install -s arch=x86_64 -s build_type=Debug ..
This will automatically
download and/or build CUnit (and, at the moment, OpenSSL).
Documentation
The documentation is still rather limited, and at the moment only available in the sources (in the
form of restructured text files in docs
and Doxygen comments in the header files), or as
a
PDF. The
intent is to automate the process of building the documentation and have them available in more
convenient formats and in the usual locations.
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:
$ ./RoundtripPong
On another terminal, start the application that will be sending the pings:
$ ./RoundtripPing 0 0 0
# payloadSize: 0 | numSamples: 0 | timeOut: 0
# Waiting for startup jitter to stabilise
# Warm up complete.
# Latency measurements (in us)
# Latency [us] Write-access time [us] Read-access time [us]
# Seconds Count median min 99% max Count median min Count median min
1 28065 17 16 23 87 28065 8 6 28065 1 0
2 28115 17 16 23 46 28115 8 6 28115 1 0
3 28381 17 16 22 46 28381 8 6 28381 1 0
4 27928 17 16 24 127 27928 8 6 27928 1 0
5 28427 17 16 20 47 28427 8 6 28427 1 0
6 27685 17 16 26 51 27685 8 6 27685 1 0
7 28391 17 16 23 47 28391 8 6 28391 1 0
8 27938 17 16 24 63 27938 8 6 27938 1 0
9 28242 17 16 24 132 28242 8 6 28242 1 0
10 28075 17 16 23 46 28075 8 6 28075 1 0
The numbers above were measured on Mac running a 4.2 GHz Intel Core i7 on December 12th 2018. From these numbers you can see how the roundtrip is very stable and the minimal latency is now down to 17 micro-seconds (used to be 25 micro-seconds) on this HW.
Performance
Reliable message throughput is over 1MS/s for very small samples and is roughly 90% of GbE with 100 byte samples, and latency is about 30us when measured using ddsperf between two Intel(R) Xeon(R) CPU E3-1270 V2 @ 3.50GHz (that’s 2012 hardware …) running Ubuntu 16.04, with the executables built on Ubuntu 18.04 using gcc 7.4.0 for a default (i.e., “RelWithDebInfo”) build.
This is with the subscriber in listener mode, using asynchronous delivery for the throughput test. The configuration is a marginally tweaked out-of-the-box configuration: an increased maximum message size and fragment size, and an increased high-water mark for the reliability window on the writer side. For details, see the scripts directory, the environment details and the throughput and latency data underlying the graphs. These also include CPU usage (thoughput and latency) and memory usage.
Configuration
The out-of-the-box configuration should usually be fine, but there are a great many options that can
be tweaked by creating an XML file with the desired settings and defining the CYCLONEDDS_URI
to
point to it. E.g. (on Linux):
$ cat cyclonedds.xml
<?xml version="1.0" encoding="UTF-8" ?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
<Domain id="any">
<General>
<NetworkInterfaceAddress>auto</NetworkInterfaceAddress>
<AllowMulticast>default</AllowMulticast>
<MaxMessageSize>65500B</MaxMessageSize>
<FragmentSize>4000B</FragmentSize>
</General>
<Internal>
<Watermarks>
<WhcHigh>500kB</WhcHigh>
</Watermarks>
</Internal>
<Tracing>
<Verbosity>config</Verbosity>
<OutputFile>stdout</OutputFile>
</Tracing>
</Domain>
</CycloneDDS>
$ export CYCLONEDDS_URI=file://$PWD/cyclonedds.xml
(on Windows, one would have to use set CYCLONEDDS_URI=file://...
instead.)
This example shows a few things:
-
NetworkInterfaceAddress
can be used to override the interface selected by default (you can use the address or the interface name). Proper use of multiple network interfaces simultaneously will come, but is not there yet. -
AllowMulticast
configures the circumstances under which multicast will be used. If the selected interface doesn’t support it, it obviously won’t be used (false
); but if it does support it, the type of the network adapter determines the default value. For a wired network, it will use multicast for initial discovery as well as for data when there are multiple peers that the data needs to go to (true
); but on a WiFi network it will use it only for initial discovery (spdp
), because multicast on WiFi is very unreliable. -
Verbosity
allows control over the tracing, “config” dumps the configuration to the trace output (which defaults to “cyclonedds.log”). Which interface is used, what multicast settings are used, etc., is all in the trace. Setting the verbosity to “finest” gives way more output on the inner workings, and there are various other levels as well. -
MaxMessageSize
andFragmentSize
control the maximum size of the RTPS messages (basically the size of the UDP payload), and the size of the fragments into which very large samples get split (which needs to be “a bit” less). Large values such as these typically improve performance over the (current) default values. -
WhcHigh
determines when the sender will wait for acknowledgements from the readers because it has buffered too much unacknowledged data. There is some auto-tuning, the (current) default value is a bit small to get really high throughput.
Background information on configuring Cyclone DDS can be found here and a list of settings is available.
Trademarks
-
“Eclipse Cyclone DDS” and “Cyclone DDS” are trademarks of the Eclipse Foundation.
-
“DDS” is a trademark of the Object Management Group, Inc.
CONTRIBUTING
Contributing to Eclipse Cyclone DDS
Thanks for your interest in this project.
Project description
Eclipse Cyclone DDS is an implementation of the OMG Data Distribution Service (DDS) specification (see http://www.omg.org/spec/DDS/ ) and the related specifications for interoperability (see http://www.omg.org/spec/DDSI-RTPS/ )
- https://projects.eclipse.org/projects/iot.cyclonedds
Developer resources
Information regarding source code management, builds, coding standards, and more.
- https://projects.eclipse.org/projects/iot.cyclonedds/developer
The project maintains the following source code repositories
- https://github.com/eclipse/cyclonedds
Eclipse Contributor Agreement
Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA).
- http://www.eclipse.org/legal/ECA.php
Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.
For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit
Contact
Contact the project developers via the project’s “dev” list.
- https://accounts.eclipse.org/mailing-list/cyclonedds-dev
Repository Summary
Checkout URI | https://github.com/eclipse-cyclonedds/cyclonedds.git |
VCS Type | git |
VCS Version | releases/0.7.x |
Last Updated | 2022-02-11 |
Dev Status | MAINTAINED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Packages
Name | Version |
---|---|
cyclonedds | 0.7.0 |
README
Eclipse Cyclone DDS
Eclipse Cyclone DDS is a very performant and robust open-source DDS implementation. 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.
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, 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);
- GIT version control system;
- CMake, version 3.7 or later;
-
OpenSSL, preferably version 1.1 or later if you want to use TLS over
TCP. You can explicitly disable it by setting
ENABLE_SSL=NO
, which is very useful for reducing the footprint or when the FindOpenSSL CMake script gives you trouble; - Java JDK, version 8 or later, e.g., OpenJDK;
- Apache Maven, version 3.5 or later.
On Ubuntu apt install maven default-jdk
should do the trick for getting Java and Maven
installed, and the rest should already be there. On Windows, installing chocolatey and choco
install git cmake openjdk maven
should get you a long way. On macOS, brew install maven cmake
and downloading and installing the JDK is easiest.
The only Java-based component is the IDL preprocessor. The run-time
libraries are pure C code, so there is no need to have Java available on “target”
machines. If desired, it is possible to do a build without Java or Maven installed by
defining BUILD_IDLC=NO
, but that effectively only gets you the core library. For the
current ROS 2 RMW layer, that is sufficient.
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
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 Travis CI and AppVeyor are
present in the repository and that there is a test suite using CTest and CUnit 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
Such a build requires the presence of CUnit. You can install this yourself, or you can choose to instead rely on the Conan packaging system that the CI build infrastructure also uses. In that case, install Conan and do:
$ conan install .. --build missing
in the build directory prior to running cmake.
The CUnit Conan package is hosted in the Bincrafters Bintray repository. In case this repository was not added to your Conan remotes list yet (and the above mentioned install command failed because it could not find the CUnit package), you can add the Bintray repository by:
$ conan remote add <REMOTE> https://api.bintray.com/conan/bincrafters/public-conan
Replace <REMOTE>
with a name that identifies the repository (e.g. bincrafters
).
For Windows, depending on the generator, you might also need to add switches to select the architecture
and build type, e.g., conan install -s arch=x86_64 -s build_type=Debug ..
This will automatically
download and/or build CUnit (and, at the moment, OpenSSL).
Documentation
The documentation is still rather limited, and at the moment only available in the sources (in the
form of restructured text files in docs
and Doxygen comments in the header files), or as
a
PDF. The
intent is to automate the process of building the documentation and have them available in more
convenient formats and in the usual locations.
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:
$ ./RoundtripPong
On another terminal, start the application that will be sending the pings:
$ ./RoundtripPing 0 0 0
# payloadSize: 0 | numSamples: 0 | timeOut: 0
# Waiting for startup jitter to stabilise
# Warm up complete.
# Latency measurements (in us)
# Latency [us] Write-access time [us] Read-access time [us]
# Seconds Count median min 99% max Count median min Count median min
1 28065 17 16 23 87 28065 8 6 28065 1 0
2 28115 17 16 23 46 28115 8 6 28115 1 0
3 28381 17 16 22 46 28381 8 6 28381 1 0
4 27928 17 16 24 127 27928 8 6 27928 1 0
5 28427 17 16 20 47 28427 8 6 28427 1 0
6 27685 17 16 26 51 27685 8 6 27685 1 0
7 28391 17 16 23 47 28391 8 6 28391 1 0
8 27938 17 16 24 63 27938 8 6 27938 1 0
9 28242 17 16 24 132 28242 8 6 28242 1 0
10 28075 17 16 23 46 28075 8 6 28075 1 0
The numbers above were measured on Mac running a 4.2 GHz Intel Core i7 on December 12th 2018. From these numbers you can see how the roundtrip is very stable and the minimal latency is now down to 17 micro-seconds (used to be 25 micro-seconds) on this HW.
Performance
Reliable message throughput is over 1MS/s for very small samples and is roughly 90% of GbE with 100 byte samples, and latency is about 30us when measured using ddsperf between two Intel(R) Xeon(R) CPU E3-1270 V2 @ 3.50GHz (that’s 2012 hardware …) running Ubuntu 16.04, with the executables built on Ubuntu 18.04 using gcc 7.4.0 for a default (i.e., “RelWithDebInfo”) build.
This is with the subscriber in listener mode, using asynchronous delivery for the throughput test. The configuration is a marginally tweaked out-of-the-box configuration: an increased maximum message size and fragment size, and an increased high-water mark for the reliability window on the writer side. For details, see the scripts directory, the environment details and the throughput and latency data underlying the graphs. These also include CPU usage (throughput and latency) and memory usage.
Configuration
The out-of-the-box configuration should usually be fine, but there are a great many options that can
be tweaked by creating an XML file with the desired settings and defining the CYCLONEDDS_URI
to
point to it. E.g. (on Linux):
$ cat cyclonedds.xml
<?xml version="1.0" encoding="UTF-8" ?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
<Domain id="any">
<General>
<NetworkInterfaceAddress>auto</NetworkInterfaceAddress>
<AllowMulticast>default</AllowMulticast>
<MaxMessageSize>65500B</MaxMessageSize>
<FragmentSize>4000B</FragmentSize>
</General>
<Internal>
<Watermarks>
<WhcHigh>500kB</WhcHigh>
</Watermarks>
</Internal>
<Tracing>
<Verbosity>config</Verbosity>
<OutputFile>stdout</OutputFile>
</Tracing>
</Domain>
</CycloneDDS>
$ export CYCLONEDDS_URI=file://$PWD/cyclonedds.xml
(on Windows, one would have to use set CYCLONEDDS_URI=file://...
instead.)
This example shows a few things:
-
NetworkInterfaceAddress
can be used to override the interface selected by default (you can use the address or the interface name). Proper use of multiple network interfaces simultaneously will come, but is not there yet. -
AllowMulticast
configures the circumstances under which multicast will be used. If the selected interface doesn’t support it, it obviously won’t be used (false
); but if it does support it, the type of the network adapter determines the default value. For a wired network, it will use multicast for initial discovery as well as for data when there are multiple peers that the data needs to go to (true
); but on a WiFi network it will use it only for initial discovery (spdp
), because multicast on WiFi is very unreliable. -
Verbosity
allows control over the tracing, “config” dumps the configuration to the trace output (which defaults to “cyclonedds.log”). Which interface is used, what multicast settings are used, etc., is all in the trace. Setting the verbosity to “finest” gives way more output on the inner workings, and there are various other levels as well. -
MaxMessageSize
andFragmentSize
control the maximum size of the RTPS messages (basically the size of the UDP payload), and the size of the fragments into which very large samples get split (which needs to be “a bit” less). Large values such as these typically improve performance over the (current) default values. -
WhcHigh
determines when the sender will wait for acknowledgements from the readers because it has buffered too much unacknowledged data. There is some auto-tuning, the (current) default value is a bit small to get really high throughput.
Background information on configuring Cyclone DDS can be found here and a list of settings is available.
Trademarks
-
“Eclipse Cyclone DDS” and “Cyclone DDS” are trademarks of the Eclipse Foundation.
-
“DDS” is a trademark of the Object Management Group, Inc.
-
“ROS” is a trademark of Open Source Robotics Foundation, Inc.
CONTRIBUTING
Contributing to Eclipse Cyclone DDS
Thanks for your interest in this project.
Project description
Eclipse Cyclone DDS is an implementation of the OMG Data Distribution Service (DDS) specification (see http://www.omg.org/spec/DDS/ ) and the related specifications for interoperability (see http://www.omg.org/spec/DDSI-RTPS/ )
- https://projects.eclipse.org/projects/iot.cyclonedds
Developer resources
Information regarding source code management, builds, coding standards, and more.
- https://projects.eclipse.org/projects/iot.cyclonedds/developer
The project maintains the following source code repositories
- https://github.com/eclipse/cyclonedds
Eclipse Contributor Agreement
Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA).
- http://www.eclipse.org/legal/ECA.php
Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.
For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit
Contact
Contact the project developers via the project’s “dev” list.
- https://accounts.eclipse.org/mailing-list/cyclonedds-dev
Repository Summary
Checkout URI | https://github.com/eclipse-cyclonedds/cyclonedds.git |
VCS Type | git |
VCS Version | releases/0.8.x |
Last Updated | 2022-02-03 |
Dev Status | MAINTAINED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Packages
Name | Version |
---|---|
cyclonedds | 0.8.2 |
README
Eclipse Cyclone DDS
Eclipse Cyclone DDS is a very performant and robust open-source DDS implementation. 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.
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, 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);
- GIT version control system;
- CMake, version 3.7 or later;
-
OpenSSL, preferably version 1.1 or later if you want to use TLS over
TCP. You can explicitly disable it by setting
ENABLE_SSL=NO
, which is very useful for reducing the footprint or when the FindOpenSSL CMake script gives you trouble; - Bison parser generator.
On Ubuntu apt install bison
should do the trick for getting Bison installed, and the rest should
already be there. 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
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> -DBUILD_EXAMPLES=ON ..
$ cmake --build .
and for Windows:
$ cd build
$ cmake -G "<generator-name>" -DCMAKE_INSTALL_PREFIX=<install-location> -DBUILD_EXAMPLES=ON ..
$ 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 Travis CI and AppVeyor are
present in the repository and that there is a test suite using CTest and CUnit 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
Such a build requires the presence of CUnit. You can install this yourself, or you can choose to instead rely on the Conan packaging system that the CI build infrastructure also uses. In that case, install Conan and do:
$ conan install .. --build missing
in the build directory prior to running cmake.
For Windows, depending on the generator, you might also need to add switches to select the architecture
and build type, e.g., conan install -s arch=x86_64 -s build_type=Debug ..
This will automatically
download and/or build CUnit (and, at the moment, OpenSSL).
Documentation
The documentation is still rather limited, and at the moment only available in the sources (in the
form of restructured text files in docs
and Doxygen comments in the header files), or as
a
PDF. The
intent is to automate the process of building the documentation and have them available in more
convenient formats and in the usual locations.
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:
$ ./RoundtripPong
On another terminal, start the application that will be sending the pings:
$ ./RoundtripPing 0 0 0
# payloadSize: 0 | numSamples: 0 | timeOut: 0
# Waiting for startup jitter to stabilise
# Warm up complete.
# Latency measurements (in us)
# Latency [us] Write-access time [us] Read-access time [us]
# Seconds Count median min 99% max Count median min Count median min
1 28065 17 16 23 87 28065 8 6 28065 1 0
2 28115 17 16 23 46 28115 8 6 28115 1 0
3 28381 17 16 22 46 28381 8 6 28381 1 0
4 27928 17 16 24 127 27928 8 6 27928 1 0
5 28427 17 16 20 47 28427 8 6 28427 1 0
6 27685 17 16 26 51 27685 8 6 27685 1 0
7 28391 17 16 23 47 28391 8 6 28391 1 0
8 27938 17 16 24 63 27938 8 6 27938 1 0
9 28242 17 16 24 132 28242 8 6 28242 1 0
10 28075 17 16 23 46 28075 8 6 28075 1 0
The numbers above were measured on Mac running a 4.2 GHz Intel Core i7 on December 12th 2018. From these numbers you can see how the roundtrip is very stable and the minimal latency is now down to 17 micro-seconds (used to be 25 micro-seconds) on this HW.
Performance
Reliable message throughput is over 1MS/s for very small samples and is roughly 90% of GbE with 100 byte samples, and latency is about 30us when measured using ddsperf between two Intel(R) Xeon(R) CPU E3-1270 V2 @ 3.50GHz (that’s 2012 hardware …) running Ubuntu 16.04, with the executables built on Ubuntu 18.04 using gcc 7.4.0 for a default (i.e., “RelWithDebInfo”) build.
This is with the subscriber in listener mode, using asynchronous delivery for the throughput test. The configuration is a marginally tweaked out-of-the-box configuration: an increased maximum message size and fragment size, and an increased high-water mark for the reliability window on the writer side. For details, see the scripts directory, the environment details and the throughput and latency data underlying the graphs. These also include CPU usage (throughput and latency) and memory usage.
Configuration
The out-of-the-box configuration should usually be fine, but there are a great many options that can
be tweaked by creating an XML file with the desired settings and defining the CYCLONEDDS_URI
to
point to it. E.g. (on Linux):
$ cat cyclonedds.xml
<?xml version="1.0" encoding="UTF-8" ?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
<Domain id="any">
<General>
<NetworkInterfaceAddress>auto</NetworkInterfaceAddress>
<AllowMulticast>default</AllowMulticast>
<MaxMessageSize>65500B</MaxMessageSize>
<FragmentSize>4000B</FragmentSize>
</General>
<Internal>
<Watermarks>
<WhcHigh>500kB</WhcHigh>
</Watermarks>
</Internal>
<Tracing>
<Verbosity>config</Verbosity>
<OutputFile>stdout</OutputFile>
</Tracing>
</Domain>
</CycloneDDS>
$ export CYCLONEDDS_URI=file://$PWD/cyclonedds.xml
(on Windows, one would have to use set CYCLONEDDS_URI=file://...
instead.)
This example shows a few things:
-
NetworkInterfaceAddress
can be used to override the interface selected by default (you can use the address or the interface name). Proper use of multiple network interfaces simultaneously will come, but is not there yet. -
AllowMulticast
configures the circumstances under which multicast will be used. If the selected interface doesn’t support it, it obviously won’t be used (false
); but if it does support it, the type of the network adapter determines the default value. For a wired network, it will use multicast for initial discovery as well as for data when there are multiple peers that the data needs to go to (true
); but on a WiFi network it will use it only for initial discovery (spdp
), because multicast on WiFi is very unreliable. -
Verbosity
allows control over the tracing, “config” dumps the configuration to the trace output (which defaults to “cyclonedds.log”). Which interface is used, what multicast settings are used, etc., is all in the trace. Setting the verbosity to “finest” gives way more output on the inner workings, and there are various other levels as well. -
MaxMessageSize
andFragmentSize
control the maximum size of the RTPS messages (basically the size of the UDP payload), and the size of the fragments into which very large samples get split (which needs to be “a bit” less). Large values such as these typically improve performance over the (current) default values. -
WhcHigh
determines when the sender will wait for acknowledgements from the readers because it has buffered too much unacknowledged data. There is some auto-tuning, the (current) default value is a bit small to get really high throughput.
Background information on configuring Cyclone DDS can be found here and a list of settings is available.
Trademarks
-
“Eclipse Cyclone DDS” and “Cyclone DDS” are trademarks of the Eclipse Foundation.
-
“DDS” is a trademark of the Object Management Group, Inc.
-
“ROS” is a trademark of Open Source Robotics Foundation, Inc.
CONTRIBUTING
Contributing to Eclipse Cyclone DDS
Thanks for your interest in this project.
Project description
Eclipse Cyclone DDS is an implementation of the OMG Data Distribution Service (DDS) specification (see http://www.omg.org/spec/DDS/ ) and the related specifications for interoperability (see http://www.omg.org/spec/DDSI-RTPS/ )
- https://projects.eclipse.org/projects/iot.cyclonedds
Developer resources
Information regarding source code management, builds, coding standards, and more.
- https://projects.eclipse.org/projects/iot.cyclonedds/developer
The project maintains the following source code repositories
- https://github.com/eclipse/cyclonedds
Eclipse Contributor Agreement
Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA).
- http://www.eclipse.org/legal/ECA.php
Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.
For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit
Contact
Contact the project developers via the project’s “dev” list.
- https://accounts.eclipse.org/mailing-list/cyclonedds-dev
Repository Summary
Checkout URI | https://github.com/eclipse-cyclonedds/cyclonedds.git |
VCS Type | git |
VCS Version | releases/0.7.x |
Last Updated | 2022-02-11 |
Dev Status | MAINTAINED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Packages
Name | Version |
---|---|
cyclonedds | 0.7.0 |
README
Eclipse Cyclone DDS
Eclipse Cyclone DDS is a very performant and robust open-source DDS implementation. 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.
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, 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);
- GIT version control system;
- CMake, version 3.7 or later;
-
OpenSSL, preferably version 1.1 or later if you want to use TLS over
TCP. You can explicitly disable it by setting
ENABLE_SSL=NO
, which is very useful for reducing the footprint or when the FindOpenSSL CMake script gives you trouble; - Java JDK, version 8 or later, e.g., OpenJDK;
- Apache Maven, version 3.5 or later.
On Ubuntu apt install maven default-jdk
should do the trick for getting Java and Maven
installed, and the rest should already be there. On Windows, installing chocolatey and choco
install git cmake openjdk maven
should get you a long way. On macOS, brew install maven cmake
and downloading and installing the JDK is easiest.
The only Java-based component is the IDL preprocessor. The run-time
libraries are pure C code, so there is no need to have Java available on “target”
machines. If desired, it is possible to do a build without Java or Maven installed by
defining BUILD_IDLC=NO
, but that effectively only gets you the core library. For the
current ROS 2 RMW layer, that is sufficient.
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
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 Travis CI and AppVeyor are
present in the repository and that there is a test suite using CTest and CUnit 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
Such a build requires the presence of CUnit. You can install this yourself, or you can choose to instead rely on the Conan packaging system that the CI build infrastructure also uses. In that case, install Conan and do:
$ conan install .. --build missing
in the build directory prior to running cmake.
The CUnit Conan package is hosted in the Bincrafters Bintray repository. In case this repository was not added to your Conan remotes list yet (and the above mentioned install command failed because it could not find the CUnit package), you can add the Bintray repository by:
$ conan remote add <REMOTE> https://api.bintray.com/conan/bincrafters/public-conan
Replace <REMOTE>
with a name that identifies the repository (e.g. bincrafters
).
For Windows, depending on the generator, you might also need to add switches to select the architecture
and build type, e.g., conan install -s arch=x86_64 -s build_type=Debug ..
This will automatically
download and/or build CUnit (and, at the moment, OpenSSL).
Documentation
The documentation is still rather limited, and at the moment only available in the sources (in the
form of restructured text files in docs
and Doxygen comments in the header files), or as
a
PDF. The
intent is to automate the process of building the documentation and have them available in more
convenient formats and in the usual locations.
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:
$ ./RoundtripPong
On another terminal, start the application that will be sending the pings:
$ ./RoundtripPing 0 0 0
# payloadSize: 0 | numSamples: 0 | timeOut: 0
# Waiting for startup jitter to stabilise
# Warm up complete.
# Latency measurements (in us)
# Latency [us] Write-access time [us] Read-access time [us]
# Seconds Count median min 99% max Count median min Count median min
1 28065 17 16 23 87 28065 8 6 28065 1 0
2 28115 17 16 23 46 28115 8 6 28115 1 0
3 28381 17 16 22 46 28381 8 6 28381 1 0
4 27928 17 16 24 127 27928 8 6 27928 1 0
5 28427 17 16 20 47 28427 8 6 28427 1 0
6 27685 17 16 26 51 27685 8 6 27685 1 0
7 28391 17 16 23 47 28391 8 6 28391 1 0
8 27938 17 16 24 63 27938 8 6 27938 1 0
9 28242 17 16 24 132 28242 8 6 28242 1 0
10 28075 17 16 23 46 28075 8 6 28075 1 0
The numbers above were measured on Mac running a 4.2 GHz Intel Core i7 on December 12th 2018. From these numbers you can see how the roundtrip is very stable and the minimal latency is now down to 17 micro-seconds (used to be 25 micro-seconds) on this HW.
Performance
Reliable message throughput is over 1MS/s for very small samples and is roughly 90% of GbE with 100 byte samples, and latency is about 30us when measured using ddsperf between two Intel(R) Xeon(R) CPU E3-1270 V2 @ 3.50GHz (that’s 2012 hardware …) running Ubuntu 16.04, with the executables built on Ubuntu 18.04 using gcc 7.4.0 for a default (i.e., “RelWithDebInfo”) build.
This is with the subscriber in listener mode, using asynchronous delivery for the throughput test. The configuration is a marginally tweaked out-of-the-box configuration: an increased maximum message size and fragment size, and an increased high-water mark for the reliability window on the writer side. For details, see the scripts directory, the environment details and the throughput and latency data underlying the graphs. These also include CPU usage (throughput and latency) and memory usage.
Configuration
The out-of-the-box configuration should usually be fine, but there are a great many options that can
be tweaked by creating an XML file with the desired settings and defining the CYCLONEDDS_URI
to
point to it. E.g. (on Linux):
$ cat cyclonedds.xml
<?xml version="1.0" encoding="UTF-8" ?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
<Domain id="any">
<General>
<NetworkInterfaceAddress>auto</NetworkInterfaceAddress>
<AllowMulticast>default</AllowMulticast>
<MaxMessageSize>65500B</MaxMessageSize>
<FragmentSize>4000B</FragmentSize>
</General>
<Internal>
<Watermarks>
<WhcHigh>500kB</WhcHigh>
</Watermarks>
</Internal>
<Tracing>
<Verbosity>config</Verbosity>
<OutputFile>stdout</OutputFile>
</Tracing>
</Domain>
</CycloneDDS>
$ export CYCLONEDDS_URI=file://$PWD/cyclonedds.xml
(on Windows, one would have to use set CYCLONEDDS_URI=file://...
instead.)
This example shows a few things:
-
NetworkInterfaceAddress
can be used to override the interface selected by default (you can use the address or the interface name). Proper use of multiple network interfaces simultaneously will come, but is not there yet. -
AllowMulticast
configures the circumstances under which multicast will be used. If the selected interface doesn’t support it, it obviously won’t be used (false
); but if it does support it, the type of the network adapter determines the default value. For a wired network, it will use multicast for initial discovery as well as for data when there are multiple peers that the data needs to go to (true
); but on a WiFi network it will use it only for initial discovery (spdp
), because multicast on WiFi is very unreliable. -
Verbosity
allows control over the tracing, “config” dumps the configuration to the trace output (which defaults to “cyclonedds.log”). Which interface is used, what multicast settings are used, etc., is all in the trace. Setting the verbosity to “finest” gives way more output on the inner workings, and there are various other levels as well. -
MaxMessageSize
andFragmentSize
control the maximum size of the RTPS messages (basically the size of the UDP payload), and the size of the fragments into which very large samples get split (which needs to be “a bit” less). Large values such as these typically improve performance over the (current) default values. -
WhcHigh
determines when the sender will wait for acknowledgements from the readers because it has buffered too much unacknowledged data. There is some auto-tuning, the (current) default value is a bit small to get really high throughput.
Background information on configuring Cyclone DDS can be found here and a list of settings is available.
Trademarks
-
“Eclipse Cyclone DDS” and “Cyclone DDS” are trademarks of the Eclipse Foundation.
-
“DDS” is a trademark of the Object Management Group, Inc.
-
“ROS” is a trademark of Open Source Robotics Foundation, Inc.
CONTRIBUTING
Contributing to Eclipse Cyclone DDS
Thanks for your interest in this project.
Project description
Eclipse Cyclone DDS is an implementation of the OMG Data Distribution Service (DDS) specification (see http://www.omg.org/spec/DDS/ ) and the related specifications for interoperability (see http://www.omg.org/spec/DDSI-RTPS/ )
- https://projects.eclipse.org/projects/iot.cyclonedds
Developer resources
Information regarding source code management, builds, coding standards, and more.
- https://projects.eclipse.org/projects/iot.cyclonedds/developer
The project maintains the following source code repositories
- https://github.com/eclipse/cyclonedds
Eclipse Contributor Agreement
Before your contribution can be accepted by the project team contributors must electronically sign the Eclipse Contributor Agreement (ECA).
- http://www.eclipse.org/legal/ECA.php
Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.
For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit
Contact
Contact the project developers via the project’s “dev” list.
- https://accounts.eclipse.org/mailing-list/cyclonedds-dev