cyclonedds package from cyclonedds repo

cyclonedds

Package Summary

Tags No category tags.
Version 0.10.5
License Eclipse Public License 2.0
Build type CMAKE
Use RECOMMENDED

Repository Summary

Checkout URI https://github.com/eclipse-cyclonedds/cyclonedds.git
VCS Type git
VCS Version releases/0.10.x
Last Updated 2024-11-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)

Package Description

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.

Additional Links

Maintainers

  • Eclipse Foundation, Inc.

Authors

No additional authors.

GitHub release Build Status Coverity Status Coverage License License Website Community

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 and ddsperf)
  • -DBUILD_DDSPERF=NO: to disable building the ddsperf tool for performance measurement
  • -DENABLE_SSL=NO: to not look for OpenSSL, remove TLS/TCP support and avoid building the plugins that implement authentication and encryption (default is AUTO to enable them if OpenSSL is found)
  • -DENABLE_SHM=NO: to not look for Iceoryx and disabled shared memory support (default is AUTO to enable it if Iceoryx is found)
  • -DENABLE_SECURITY=NO: to not build the security interfaces and hooks in the core code, nor the plugins (one can enable security without OpenSSL present, you’ll just have to find plugins elsewhere in that case)
  • -DENABLE_LIFESPAN=NO: to exclude support for finite lifespans QoS
  • -DENABLE_DEADLINE_MISSED=NO: to exclude support for finite deadline QoS settings
  • -DENABLE_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.

ThroughputThroughput

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 priority 0 for normal interfaces and 2 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.
CHANGELOG

Changelog for Eclipse Cyclone DDS

Unreleased

V0.7.0 (2020-08-06) -----------------------------------------------------------------------------------------------

This release brings support for the DDS Security 1.1 specification:authentication, access control and encryption. It also provides significant performance improvements with large samples, by better scheduling of retransmit requests and by avoiding the occasional excessive latency caused by dropping the heartbeat rate too soon.

One can choose to build Cyclone DDS without support for DDS Security if one wants to reduce the size of the resulting library. The default plug-ins are built only if security is enabled and OpenSSL is available, as those are implemented using the cryptographic operations and I/O primitives for handling certificates and exchanging keys that OpenSSL provides. If one chooses to exclude security support from the build, setting any security related property or adding it to the configuration files will result in participant creation failing with a "precondition not met" error.

A lot of effort has gone into testing and checking that malformed or unexpected messages are handled correctly, that message authentication codes are checked and that no data never goes out unencrypted by accident. Still, it is only prudent to assume the existence of vulnerabilities.

Noteworthy bug fixes:

  • DATA_AVAILABLE was not always triggered when by a dispose and sometimes triggered in the absence of an observable state change (arrival of a dispose for an already-disposed instance where the dispose had not yet been read);
  • Restores functionality of the "raw ethernet" mode as well as IPv6 with link-local addresses, both accidentally broken in 0.6.0;
  • Fixes a crash in processing endpoint discovery data containing unrecognised locator kinds;
  • Fixes type conversion for local historical data (e.g., mixed use of ROS 2 C/C++ type supports in combination with transient-local endpoints within a single process);
  • Fixes a use-after-free of "lease" objects with manual-by-topic writers;
  • Mark instance as "alive" in the reader history and generate an invalid sample to notify the application even if the sample itself is dropped because the same or a later one is present already (e.g., on reconnecting to a transient-local writer);
  • Fix a crash when doing an instance lookup on a built-in topic using the key value;
  • No longer auto-dispose instances as soon as some registered writer disappears, instead do it only when all of them have unregistered it;
  • Fix performance of read_instance and take_instance by performing a proper instance lookup.

V0.6.0 (2020-05-21) -----------------------------------------------------------------------------------------------

  • Support for mixed-language programming by supporting multiple (de)serializers for a single topic in a single process. This way, a program that consists of, say, C and C++ can use a different representation of the data in C than in C++. Before, all readers/writers in the process would be forced to use the same representation (or perform an additional copy). Currently C is still the only natively supported language, but one can use an evolving-but-reasonable-stable interface to implement different mappings.
  • Improved QoS support: full support for deadline, lifespan and liveliness. The first is for generating notifications when a configured instance update rate is not achieved, the second for automatically removing stale samples, the third for different modes of monitoring the liveliness of peers.
  • Improved scalability in matching readers and writers. Before it used to try matching a new local or remote reader or writer with all known local & remote entities, now only with the right group with the correct topic name.
  • Improved tracing: discovery data is now printed properly and user samples have more type information allowing floating-point and signed numbers to be traced in a more readable form.
  • Extension of platform support
    • Known to work on FreeBSD, CheriBSD
    • Known to work with the musl C library
  • Windows-specific changes
    • Fixes multicasts to addresses also used by non-Cyclone processes (caused by accidentally linking with an old sockets library)
    • Correct handling of non-English network interface names

0.5.1 (2020-03-11)

An interim tag for the benefit of ROS2

  • Enable QOS features: liveliness, lifespan, deadline
  • Fix issues on Windows where multicast data was not received

V0.5.0 (2019-11-21)

This is the fist release candidate for the long overdue second release of Eclipse Cyclone DDS. We are updating the version number from 0.1 to 0.5 to make up for the lack of more timely releases and to reflect that progress towards a 1.0 release (a minimum profile DDS implementation + DDS security) has been more significant than a version of "0.2" would suggest.

Updates since the first release have been legion, pretty much without impact on application code or interoperatbility on the network. Some of the highlights:

  • Support for ROS2 Dashing and Eloquent (via an adaption layer).
  • Support for an arbitrary number of concurrent DDS domains (fully independent instantiations of DDS) in a single process.
  • Abstracting the notion of samples, types and reader history caches, allowing overriding the default implementations of these to get behaviours more suited to the applications. This is particularly relevant to language bindings and embedding Cyclone DDS in other frameworks, such as ROS2.
  • Platform support is extended beyond the usual Linux/Windows/macOS: FreeRTOS is now known to work, as is Solaris 2.6 on sun4m machines.
  • Acceptance of some malformed messages from certain implementations improved interoperability on the wire.

Limitations on backwards compatibility:

  • A change in how implicitly created "publisher" and "subscriber" entities are handled: they now never lose their "implicitness", and in consequence, are now deleted when their last child disappears rather than deleted when their one child disappears.
  • The set of entities that can be attached to a waitset is now restricted to those owned by the parent of the waitset, before one was allowed to attach entities from different participants to the same waitset, which is tantamount to a bug.
  • A participant entity now has a parent. The "get_parent" operation no longer returns 0 for a participant because of the addition of two additional levels to the entity hierarchy: a domain, possibly containing multiple participants; and one that represents the entire library.
  • The data from a reader for a built-in topic has been extended, breaking binary compatibility.

V0.1.0 (2019-03-06)

Eclipse Cyclone DDS’ first release!

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged cyclonedds at Robotics Stack Exchange

cyclonedds package from cyclonedds repo

cyclonedds

Package Summary

Tags No category tags.
Version 0.10.5
License Eclipse Public License 2.0
Build type CMAKE
Use RECOMMENDED

Repository Summary

Checkout URI https://github.com/eclipse-cyclonedds/cyclonedds.git
VCS Type git
VCS Version releases/0.10.x
Last Updated 2024-11-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)

Package Description

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.

Additional Links

Maintainers

  • Eclipse Foundation, Inc.

Authors

No additional authors.

GitHub release Build Status Coverity Status Coverage License License Website Community

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 and ddsperf)
  • -DBUILD_DDSPERF=NO: to disable building the ddsperf tool for performance measurement
  • -DENABLE_SSL=NO: to not look for OpenSSL, remove TLS/TCP support and avoid building the plugins that implement authentication and encryption (default is AUTO to enable them if OpenSSL is found)
  • -DENABLE_SHM=NO: to not look for Iceoryx and disabled shared memory support (default is AUTO to enable it if Iceoryx is found)
  • -DENABLE_SECURITY=NO: to not build the security interfaces and hooks in the core code, nor the plugins (one can enable security without OpenSSL present, you’ll just have to find plugins elsewhere in that case)
  • -DENABLE_LIFESPAN=NO: to exclude support for finite lifespans QoS
  • -DENABLE_DEADLINE_MISSED=NO: to exclude support for finite deadline QoS settings
  • -DENABLE_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.

ThroughputThroughput

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 priority 0 for normal interfaces and 2 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.
CHANGELOG

Changelog for Eclipse Cyclone DDS

Unreleased

V0.7.0 (2020-08-06) -----------------------------------------------------------------------------------------------

This release brings support for the DDS Security 1.1 specification:authentication, access control and encryption. It also provides significant performance improvements with large samples, by better scheduling of retransmit requests and by avoiding the occasional excessive latency caused by dropping the heartbeat rate too soon.

One can choose to build Cyclone DDS without support for DDS Security if one wants to reduce the size of the resulting library. The default plug-ins are built only if security is enabled and OpenSSL is available, as those are implemented using the cryptographic operations and I/O primitives for handling certificates and exchanging keys that OpenSSL provides. If one chooses to exclude security support from the build, setting any security related property or adding it to the configuration files will result in participant creation failing with a "precondition not met" error.

A lot of effort has gone into testing and checking that malformed or unexpected messages are handled correctly, that message authentication codes are checked and that no data never goes out unencrypted by accident. Still, it is only prudent to assume the existence of vulnerabilities.

Noteworthy bug fixes:

  • DATA_AVAILABLE was not always triggered when by a dispose and sometimes triggered in the absence of an observable state change (arrival of a dispose for an already-disposed instance where the dispose had not yet been read);
  • Restores functionality of the "raw ethernet" mode as well as IPv6 with link-local addresses, both accidentally broken in 0.6.0;
  • Fixes a crash in processing endpoint discovery data containing unrecognised locator kinds;
  • Fixes type conversion for local historical data (e.g., mixed use of ROS 2 C/C++ type supports in combination with transient-local endpoints within a single process);
  • Fixes a use-after-free of "lease" objects with manual-by-topic writers;
  • Mark instance as "alive" in the reader history and generate an invalid sample to notify the application even if the sample itself is dropped because the same or a later one is present already (e.g., on reconnecting to a transient-local writer);
  • Fix a crash when doing an instance lookup on a built-in topic using the key value;
  • No longer auto-dispose instances as soon as some registered writer disappears, instead do it only when all of them have unregistered it;
  • Fix performance of read_instance and take_instance by performing a proper instance lookup.

V0.6.0 (2020-05-21) -----------------------------------------------------------------------------------------------

  • Support for mixed-language programming by supporting multiple (de)serializers for a single topic in a single process. This way, a program that consists of, say, C and C++ can use a different representation of the data in C than in C++. Before, all readers/writers in the process would be forced to use the same representation (or perform an additional copy). Currently C is still the only natively supported language, but one can use an evolving-but-reasonable-stable interface to implement different mappings.
  • Improved QoS support: full support for deadline, lifespan and liveliness. The first is for generating notifications when a configured instance update rate is not achieved, the second for automatically removing stale samples, the third for different modes of monitoring the liveliness of peers.
  • Improved scalability in matching readers and writers. Before it used to try matching a new local or remote reader or writer with all known local & remote entities, now only with the right group with the correct topic name.
  • Improved tracing: discovery data is now printed properly and user samples have more type information allowing floating-point and signed numbers to be traced in a more readable form.
  • Extension of platform support
    • Known to work on FreeBSD, CheriBSD
    • Known to work with the musl C library
  • Windows-specific changes
    • Fixes multicasts to addresses also used by non-Cyclone processes (caused by accidentally linking with an old sockets library)
    • Correct handling of non-English network interface names

0.5.1 (2020-03-11)

An interim tag for the benefit of ROS2

  • Enable QOS features: liveliness, lifespan, deadline
  • Fix issues on Windows where multicast data was not received

V0.5.0 (2019-11-21)

This is the fist release candidate for the long overdue second release of Eclipse Cyclone DDS. We are updating the version number from 0.1 to 0.5 to make up for the lack of more timely releases and to reflect that progress towards a 1.0 release (a minimum profile DDS implementation + DDS security) has been more significant than a version of "0.2" would suggest.

Updates since the first release have been legion, pretty much without impact on application code or interoperatbility on the network. Some of the highlights:

  • Support for ROS2 Dashing and Eloquent (via an adaption layer).
  • Support for an arbitrary number of concurrent DDS domains (fully independent instantiations of DDS) in a single process.
  • Abstracting the notion of samples, types and reader history caches, allowing overriding the default implementations of these to get behaviours more suited to the applications. This is particularly relevant to language bindings and embedding Cyclone DDS in other frameworks, such as ROS2.
  • Platform support is extended beyond the usual Linux/Windows/macOS: FreeRTOS is now known to work, as is Solaris 2.6 on sun4m machines.
  • Acceptance of some malformed messages from certain implementations improved interoperability on the wire.

Limitations on backwards compatibility:

  • A change in how implicitly created "publisher" and "subscriber" entities are handled: they now never lose their "implicitness", and in consequence, are now deleted when their last child disappears rather than deleted when their one child disappears.
  • The set of entities that can be attached to a waitset is now restricted to those owned by the parent of the waitset, before one was allowed to attach entities from different participants to the same waitset, which is tantamount to a bug.
  • A participant entity now has a parent. The "get_parent" operation no longer returns 0 for a participant because of the addition of two additional levels to the entity hierarchy: a domain, possibly containing multiple participants; and one that represents the entire library.
  • The data from a reader for a built-in topic has been extended, breaking binary compatibility.

V0.1.0 (2019-03-06)

Eclipse Cyclone DDS’ first release!

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Dependant Packages

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged cyclonedds at Robotics Stack Exchange

cyclonedds package from cyclonedds repo

cyclonedds

Package Summary

Tags No category tags.
Version 0.10.5
License Eclipse Public License 2.0
Build type CMAKE
Use RECOMMENDED

Repository Summary

Checkout URI https://github.com/eclipse-cyclonedds/cyclonedds.git
VCS Type git
VCS Version releases/0.10.x
Last Updated 2024-11-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)

Package Description

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.

Additional Links

Maintainers

  • Eclipse Foundation, Inc.

Authors

No additional authors.

GitHub release Build Status Coverity Status Coverage License License Website Community

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 and ddsperf)
  • -DBUILD_DDSPERF=NO: to disable building the ddsperf tool for performance measurement
  • -DENABLE_SSL=NO: to not look for OpenSSL, remove TLS/TCP support and avoid building the plugins that implement authentication and encryption (default is AUTO to enable them if OpenSSL is found)
  • -DENABLE_SHM=NO: to not look for Iceoryx and disabled shared memory support (default is AUTO to enable it if Iceoryx is found)
  • -DENABLE_SECURITY=NO: to not build the security interfaces and hooks in the core code, nor the plugins (one can enable security without OpenSSL present, you’ll just have to find plugins elsewhere in that case)
  • -DENABLE_LIFESPAN=NO: to exclude support for finite lifespans QoS
  • -DENABLE_DEADLINE_MISSED=NO: to exclude support for finite deadline QoS settings
  • -DENABLE_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.

ThroughputThroughput

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 priority 0 for normal interfaces and 2 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.
CHANGELOG

Changelog for Eclipse Cyclone DDS

Unreleased

V0.7.0 (2020-08-06) -----------------------------------------------------------------------------------------------

This release brings support for the DDS Security 1.1 specification:authentication, access control and encryption. It also provides significant performance improvements with large samples, by better scheduling of retransmit requests and by avoiding the occasional excessive latency caused by dropping the heartbeat rate too soon.

One can choose to build Cyclone DDS without support for DDS Security if one wants to reduce the size of the resulting library. The default plug-ins are built only if security is enabled and OpenSSL is available, as those are implemented using the cryptographic operations and I/O primitives for handling certificates and exchanging keys that OpenSSL provides. If one chooses to exclude security support from the build, setting any security related property or adding it to the configuration files will result in participant creation failing with a "precondition not met" error.

A lot of effort has gone into testing and checking that malformed or unexpected messages are handled correctly, that message authentication codes are checked and that no data never goes out unencrypted by accident. Still, it is only prudent to assume the existence of vulnerabilities.

Noteworthy bug fixes:

  • DATA_AVAILABLE was not always triggered when by a dispose and sometimes triggered in the absence of an observable state change (arrival of a dispose for an already-disposed instance where the dispose had not yet been read);
  • Restores functionality of the "raw ethernet" mode as well as IPv6 with link-local addresses, both accidentally broken in 0.6.0;
  • Fixes a crash in processing endpoint discovery data containing unrecognised locator kinds;
  • Fixes type conversion for local historical data (e.g., mixed use of ROS 2 C/C++ type supports in combination with transient-local endpoints within a single process);
  • Fixes a use-after-free of "lease" objects with manual-by-topic writers;
  • Mark instance as "alive" in the reader history and generate an invalid sample to notify the application even if the sample itself is dropped because the same or a later one is present already (e.g., on reconnecting to a transient-local writer);
  • Fix a crash when doing an instance lookup on a built-in topic using the key value;
  • No longer auto-dispose instances as soon as some registered writer disappears, instead do it only when all of them have unregistered it;
  • Fix performance of read_instance and take_instance by performing a proper instance lookup.

V0.6.0 (2020-05-21) -----------------------------------------------------------------------------------------------

  • Support for mixed-language programming by supporting multiple (de)serializers for a single topic in a single process. This way, a program that consists of, say, C and C++ can use a different representation of the data in C than in C++. Before, all readers/writers in the process would be forced to use the same representation (or perform an additional copy). Currently C is still the only natively supported language, but one can use an evolving-but-reasonable-stable interface to implement different mappings.
  • Improved QoS support: full support for deadline, lifespan and liveliness. The first is for generating notifications when a configured instance update rate is not achieved, the second for automatically removing stale samples, the third for different modes of monitoring the liveliness of peers.
  • Improved scalability in matching readers and writers. Before it used to try matching a new local or remote reader or writer with all known local & remote entities, now only with the right group with the correct topic name.
  • Improved tracing: discovery data is now printed properly and user samples have more type information allowing floating-point and signed numbers to be traced in a more readable form.
  • Extension of platform support
    • Known to work on FreeBSD, CheriBSD
    • Known to work with the musl C library
  • Windows-specific changes
    • Fixes multicasts to addresses also used by non-Cyclone processes (caused by accidentally linking with an old sockets library)
    • Correct handling of non-English network interface names

0.5.1 (2020-03-11)

An interim tag for the benefit of ROS2

  • Enable QOS features: liveliness, lifespan, deadline
  • Fix issues on Windows where multicast data was not received

V0.5.0 (2019-11-21)

This is the fist release candidate for the long overdue second release of Eclipse Cyclone DDS. We are updating the version number from 0.1 to 0.5 to make up for the lack of more timely releases and to reflect that progress towards a 1.0 release (a minimum profile DDS implementation + DDS security) has been more significant than a version of "0.2" would suggest.

Updates since the first release have been legion, pretty much without impact on application code or interoperatbility on the network. Some of the highlights:

  • Support for ROS2 Dashing and Eloquent (via an adaption layer).
  • Support for an arbitrary number of concurrent DDS domains (fully independent instantiations of DDS) in a single process.
  • Abstracting the notion of samples, types and reader history caches, allowing overriding the default implementations of these to get behaviours more suited to the applications. This is particularly relevant to language bindings and embedding Cyclone DDS in other frameworks, such as ROS2.
  • Platform support is extended beyond the usual Linux/Windows/macOS: FreeRTOS is now known to work, as is Solaris 2.6 on sun4m machines.
  • Acceptance of some malformed messages from certain implementations improved interoperability on the wire.

Limitations on backwards compatibility:

  • A change in how implicitly created "publisher" and "subscriber" entities are handled: they now never lose their "implicitness", and in consequence, are now deleted when their last child disappears rather than deleted when their one child disappears.
  • The set of entities that can be attached to a waitset is now restricted to those owned by the parent of the waitset, before one was allowed to attach entities from different participants to the same waitset, which is tantamount to a bug.
  • A participant entity now has a parent. The "get_parent" operation no longer returns 0 for a participant because of the addition of two additional levels to the entity hierarchy: a domain, possibly containing multiple participants; and one that represents the entire library.
  • The data from a reader for a built-in topic has been extended, breaking binary compatibility.

V0.1.0 (2019-03-06)

Eclipse Cyclone DDS’ first release!

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Dependant Packages

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged cyclonedds at Robotics Stack Exchange

cyclonedds package from autodrrt repo

autonomous_emergency_braking control_performance_analysis control_validator external_cmd_selector joy_controller lane_departure_checker mpc_lateral_controller obstacle_collision_checker operation_mode_transition_manager pid_longitudinal_controller predicted_path_checker pure_pursuit shift_decider trajectory_follower_base trajectory_follower_node vehicle_cmd_gate diagnostic_converter kinematic_evaluator localization_evaluator planning_evaluator ekf_localizer geo_pose_projector gyro_odometer ar_tag_based_localizer landmark_manager localization_error_monitor localization_util ndt_scan_matcher pose2twist pose_initializer pose_instability_detector stop_filter tree_structured_parzen_estimator twist2accel yabloc_common yabloc_image_processing yabloc_monitor yabloc_particle_filter yabloc_pose_initializer map_height_fitter map_loader map_projection_loader map_tf_generator lanelet2_map_preprocessor ros2_bevdet ros2_bevformer bevfusion bytetrack cluster_merger compare_map_segmentation crosswalk_traffic_light_estimator detected_object_feature_remover detected_object_validation detection_by_tracker elevation_map_loader euclidean_cluster front_vehicle_velocity_estimator ground_segmentation heatmap_visualizer image_projection_based_fusion lidar_apollo_instance_segmentation lidar_apollo_segmentation_tvm lidar_apollo_segmentation_tvm_nodes lidar_centerpoint lidar_centerpoint_tvm map_based_prediction multi_object_tracker object_merger object_range_splitter object_velocity_splitter occupancy_grid_map_outlier_filter probabilistic_occupancy_grid_map radar_crossing_objects_noise_filter radar_fusion_to_detected_object radar_object_clustering radar_object_tracker radar_tracks_msgs_converter shape_estimation simple_object_merger tensorrt_classifier tensorrt_yolo tensorrt_yolox tracking_object_merger traffic_light_arbiter traffic_light_classifier traffic_light_fine_detector traffic_light_map_based_detector traffic_light_multi_camera_fusion traffic_light_occlusion_predictor traffic_light_ssd_fine_detector traffic_light_visualization behavior_path_avoidance_by_lane_change_module behavior_path_avoidance_module behavior_path_external_request_lane_change_module behavior_path_goal_planner_module behavior_path_lane_change_module behavior_path_planner behavior_path_planner_common behavior_path_side_shift_module behavior_path_start_planner_module behavior_velocity_blind_spot_module behavior_velocity_crosswalk_module behavior_velocity_detection_area_module behavior_velocity_intersection_module behavior_velocity_no_drivable_lane_module behavior_velocity_no_stopping_area_module behavior_velocity_occlusion_spot_module behavior_velocity_out_of_lane_module behavior_velocity_planner behavior_velocity_planner_common behavior_velocity_run_out_module behavior_velocity_speed_bump_module behavior_velocity_stop_line_module behavior_velocity_template_module behavior_velocity_traffic_light_module behavior_velocity_virtual_traffic_light_module behavior_velocity_walkway_module costmap_generator external_velocity_limit_selector freespace_planner freespace_planning_algorithms mission_planner motion_velocity_smoother objects_of_interest_marker_interface obstacle_avoidance_planner obstacle_cruise_planner obstacle_stop_planner obstacle_velocity_limiter path_smoother planning_debug_tools planning_test_utils planning_topic_converter planning_validator route_handler rtc_interface rtc_replayer bezier_sampler frenet_planner path_sampler sampler_common scenario_selector static_centerline_optimizer surround_obstacle_checker gnss_poser image_diagnostics image_transport_decompressor imu_corrector livox_tag_filter pointcloud_preprocessor radar_scan_to_pointcloud2 radar_static_pointcloud_filter radar_threshold_filter radar_tracks_noise_filter tier4_pcl_extensions vehicle_velocity_converter autoware_auto_msgs_adapter bluetooth_monitor component_state_monitor default_ad_api ad_api_adaptors ad_api_visualizers automatic_pose_initializer diagnostic_graph_aggregator dummy_diag_publisher dummy_infrastructure duplicated_node_checker emergency_handler mrm_comfortable_stop_operator mrm_emergency_stop_operator system_error_monitor system_monitor topic_state_monitor velodyne_monitor accel_brake_map_calibrator external_cmd_converter raw_vehicle_cmd_converter steer_offset_estimator vehicle_info_util launch launch_ros autoware_ad_api_specs autoware_adapi_v1_msgs autoware_adapi_version_msgs autoware_auto_common autoware_auto_geometry autoware_auto_control_msgs autoware_auto_geometry_msgs autoware_auto_mapping_msgs autoware_auto_msgs autoware_auto_perception_msgs autoware_auto_planning_msgs autoware_auto_system_msgs autoware_auto_vehicle_msgs autoware_auto_perception_rviz_plugin autoware_auto_tf2 autoware_cmake autoware_lint_common autoware_utils lanelet2_extension autoware_common_msgs autoware_control_msgs autoware_localization_msgs autoware_map_msgs autoware_perception_msgs autoware_planning_msgs autoware_sensing_msgs autoware_system_msgs autoware_vehicle_msgs autoware_point_types autoware_testing bag_time_manager_rviz_plugin component_interface_specs component_interface_tools component_interface_utils cuda_utils fake_test_node geography_utils global_parameter_loader glog_component goal_distance_calculator grid_map_utils interpolation kalman_filter motion_utils object_recognition_utils osqp_interface path_distance_calculator perception_utils polar_grid qp_interface rtc_manager_rviz_plugin signal_processing tensorrt_common tier4_adapi_rviz_plugin tier4_api_utils tier4_automatic_goal_rviz_plugin tier4_autoware_utils tier4_calibration_rviz_plugin tier4_camera_view_rviz_plugin tier4_control_rviz_plugin tier4_datetime_rviz_plugin tier4_debug_rviz_plugin tier4_debug_tools tier4_localization_rviz_plugin tier4_perception_rviz_plugin tier4_planning_rviz_plugin tier4_screen_capture_rviz_plugin tier4_simulated_clock_rviz_plugin tier4_state_rviz_plugin tier4_system_rviz_plugin tier4_target_object_type_rviz_plugin tier4_traffic_light_rviz_plugin tier4_vehicle_rviz_plugin time_utils simulator_compatibility_test traffic_light_recognition_marker_publisher traffic_light_utils tvm_utility dma_customer_msg dma_transfer eagleye_coordinate eagleye_navigation eagleye_msgs eagleye_rt eagleye_can_velocity_converter eagleye_fix2kml eagleye_geo_pose_converter eagleye_geo_pose_fusion eagleye_gnss_converter eagleye_tf llh_converter morai_msgs mussp ndt_omp orocos_kdl python_orocos_kdl pointcloud_to_laserscan rtklib_bridge rtklib_msgs autoware_external_api_msgs autoware_iv_external_api_adaptor autoware_iv_internal_api_adaptor awapi_awiv_adapter tier4_api_msgs tier4_auto_msgs_converter tier4_control_msgs tier4_debug_msgs tier4_external_api_msgs tier4_hmi_msgs tier4_localization_msgs tier4_map_msgs tier4_perception_msgs tier4_planning_msgs tier4_rtc_msgs tier4_simulation_msgs tier4_system_msgs tier4_v2x_msgs tier4_vehicle_msgs io_opt tier4_autoware_api_launch tier4_control_launch tier4_localization_launch tier4_map_launch tier4_perception_launch tier4_planning_launch tier4_sensing_launch tier4_simulator_launch tier4_system_launch tier4_vehicle_launch fastrtps cyclonedds lanelet2 lanelet2_core lanelet2_examples lanelet2_io lanelet2_maps lanelet2_matching lanelet2_projection lanelet2_python lanelet2_routing lanelet2_traffic_rules lanelet2_validation sophus angles behaviortree_cpp_v3 bond bond_core bondcpp bondpy smclib test_bond cudnn_cmake_module diagnostic_aggregator diagnostic_common_diagnostics diagnostic_updater diagnostics self_test filters geodesy geographic_info geographic_msgs grid_map grid_map_cmake_helpers grid_map_core grid_map_costmap_2d grid_map_cv grid_map_demos grid_map_filters grid_map_loader grid_map_msgs grid_map_octomap grid_map_pcl grid_map_ros grid_map_rviz_plugin grid_map_sdf grid_map_visualization mrt_cmake_modules nav2_amcl nav2_behavior_tree nav2_behaviors nav2_bringup nav2_bt_navigator nav2_collision_monitor nav2_common nav2_controller nav2_core nav2_costmap_2d costmap_queue dwb_core dwb_critics dwb_msgs dwb_plugins nav2_dwb_controller nav_2d_msgs nav_2d_utils nav2_lifecycle_manager nav2_map_server nav2_msgs nav2_navfn_planner nav2_planner nav2_regulated_pure_pursuit_controller nav2_rotation_shim_controller nav2_rviz_plugins nav2_simple_commander nav2_smac_planner nav2_smoother nav2_system_tests nav2_theta_star_planner nav2_util nav2_velocity_smoother nav2_voxel_grid nav2_waypoint_follower navigation2 dynamic_edt_3d octomap octovis octomap_msgs osqp_vendor pacmod3_msgs pcl_msgs pcl_conversions pcl_ros perception_pcl point_cloud_msg_wrapper radar_msgs can_msgs rqt_tf_tree tensorrt_cmake_module topic_tools topic_tools_interfaces tvm_vendor cv_bridge image_geometry opencv_tests vision_opencv xacro rviz2 rviz_assimp_vendor rviz_common rviz_default_plugins rviz_ogre_vendor rviz_rendering rviz_rendering_tests rviz_visual_testing_framework dummy_perception_publisher fault_injection simple_planning_simulator classformsg node_v2x image_view v4l2_camera can_interface_custom cgi430_can_driver cgi610_driver ARS408_driver data_format_dump data_preprocess_launch lidar_centerpoint_collect lidar_saver message_sync time_cal camera_calibration direct_visual_lidar_calibration multi_lidar_calibration

Package Summary

Tags No category tags.
Version 0.9.1
License Eclipse Public License 2.0
Build type CMAKE
Use RECOMMENDED

Repository Summary

Checkout URI https://github.com/ieiauto/autodrrt.git
VCS Type git
VCS Version main
Last Updated 2024-09-19
Dev Status UNMAINTAINED
CI status No Continuous Integration
Released UNRELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Package Description

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.

Additional Links

Maintainers

  • Eclipse Foundation, Inc.

Authors

No additional authors.

Build Status Coverity Status Coverage License License

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-throuhgput, 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 interoperation 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.10 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 (this requires CUnit, see Contributing to Eclipse Cyclone DDS below for more information)
  • -DBUILD_IDLC=NO: to disable building the IDL compiler (affects building examples, tests and ddsperf)
  • -DBUILD_DDSPERF=NO: to disable building the ddsperf tool for performance measurement
  • -DENABLE_SSL=NO: to not look for OpenSSL, remove TLS/TCP support and avoid building the plugins that implement authentication and encryption (default is AUTO to enable them if OpenSSL is found)
  • -DENABLE_SHM=NO: to not look for Iceoryx and disabled shared memory support (default is AUTO to enable it if Iceoryx is found)
  • -DENABLE_SECURITY=NO: to not build the security interfaces and hooks in the core code, nor the plugins (one can enable security without OpenSSL present, you’ll just have to find plugins elsewhere in that case)
  • -DENABLE_LIFESPAN=NO: to exclude support for finite lifespans QoS
  • -DENABLE_DEADLINE_MISSED=NO: to exclude support for finite deadline QoS settings
  • -DENABLE_TYPE_DISCOVERY=YES: to include support for type discovery and checking type compatibility (likely to become enabled by default in the future)
  • -DENABLE_TOPIC_DISCOVERY=YES: to include support for topic discovery (requires -DENABLE_TYPE_DISCOVERY=YES; somewhat likely to become enabled by default in the future)
  • -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 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 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.

ThroughputThroughput

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>
        <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 priority 0 for normal interfaces and 2 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.
  • 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.
CHANGELOG

Changelog for Eclipse Cyclone DDS

Unreleased

V0.7.0 (2020-08-06) -----------------------------------------------------------------------------------------------

This release brings support for the DDS Security 1.1 specification:authentication, access control and encryption. It also provides significant performance improvements with large samples, by better scheduling of retransmit requests and by avoiding the occasional excessive latency caused by dropping the heartbeat rate too soon.

One can choose to build Cyclone DDS without support for DDS Security if one wants to reduce the size of the resulting library. The default plug-ins are built only if security is enabled and OpenSSL is available, as those are implemented using the cryptographic operations and I/O primitives for handling certificates and exchanging keys that OpenSSL provides. If one chooses to exclude security support from the build, setting any security related property or adding it to the configuration files will result in participant creation failing with a "precondition not met" error.

A lot of effort has gone into testing and checking that malformed or unexpected messages are handled correctly, that message authentication codes are checked and that no data never goes out unencrypted by accident. Still, it is only prudent to assume the existence of vulnerabilities.

Noteworthy bug fixes:

  • DATA_AVAILABLE was not always triggered when by a dispose and sometimes triggered in the absence of an observable state change (arrival of a dispose for an already-disposed instance where the dispose had not yet been read);
  • Restores functionality of the "raw ethernet" mode as well as IPv6 with link-local addresses, both accidentally broken in 0.6.0;
  • Fixes a crash in processing endpoint discovery data containing unrecognised locator kinds;
  • Fixes type conversion for local historical data (e.g., mixed use of ROS 2 C/C++ type supports in combination with transient-local endpoints within a single process);
  • Fixes a use-after-free of "lease" objects with manual-by-topic writers;
  • Mark instance as "alive" in the reader history and generate an invalid sample to notify the application even if the sample itself is dropped because the same or a later one is present already (e.g., on reconnecting to a transient-local writer);
  • Fix a crash when doing an instance lookup on a built-in topic using the key value;
  • No longer auto-dispose instances as soon as some registered writer disappears, instead do it only when all of them have unregistered it;
  • Fix performance of read_instance and take_instance by performing a proper instance lookup.

V0.6.0 (2020-05-21) -----------------------------------------------------------------------------------------------

  • Support for mixed-language programming by supporting multiple (de)serializers for a single topic in a single process. This way, a program that consists of, say, C and C++ can use a different representation of the data in C than in C++. Before, all readers/writers in the process would be forced to use the same representation (or perform an additional copy). Currently C is still the only natively supported language, but one can use an evolving-but-reasonable-stable interface to implement different mappings.
  • Improved QoS support: full support for deadline, lifespan and liveliness. The first is for generating notifications when a configured instance update rate is not achieved, the second for automatically removing stale samples, the third for different modes of monitoring the liveliness of peers.
  • Improved scalability in matching readers and writers. Before it used to try matching a new local or remote reader or writer with all known local & remote entities, now only with the right group with the correct topic name.
  • Improved tracing: discovery data is now printed properly and user samples have more type information allowing floating-point and signed numbers to be traced in a more readable form.
  • Extension of platform support
    • Known to work on FreeBSD, CheriBSD
    • Known to work with the musl C library
  • Windows-specific changes
    • Fixes multicasts to addresses also used by non-Cyclone processes (caused by accidentally linking with an old sockets library)
    • Correct handling of non-English network interface names

0.5.1 (2020-03-11)

An interim tag for the benefit of ROS2

  • Enable QOS features: liveliness, lifespan, deadline
  • Fix issues on Windows where multicast data was not received

V0.5.0 (2019-11-21)

This is the fist release candidate for the long overdue second release of Eclipse Cyclone DDS. We are updating the version number from 0.1 to 0.5 to make up for the lack of more timely releases and to reflect that progress towards a 1.0 release (a minimum profile DDS implementation + DDS security) has been more significant than a version of "0.2" would suggest.

Updates since the first release have been legion, pretty much without impact on application code or interoperatbility on the network. Some of the highlights:

  • Support for ROS2 Dashing and Eloquent (via an adaption layer).
  • Support for an arbitrary number of concurrent DDS domains (fully independent instantiations of DDS) in a single process.
  • Abstracting the notion of samples, types and reader history caches, allowing overriding the default implementations of these to get behaviours more suited to the applications. This is particularly relevant to language bindings and embedding Cyclone DDS in other frameworks, such as ROS2.
  • Platform support is extended beyond the usual Linux/Windows/macOS: FreeRTOS is now known to work, as is Solaris 2.6 on sun4m machines.
  • Acceptance of some malformed messages from certain implementations improved interoperability on the wire.

Limitations on backwards compatibility:

  • A change in how implicitly created "publisher" and "subscriber" entities are handled: they now never lose their "implicitness", and in consequence, are now deleted when their last child disappears rather than deleted when their one child disappears.
  • The set of entities that can be attached to a waitset is now restricted to those owned by the parent of the waitset, before one was allowed to attach entities from different participants to the same waitset, which is tantamount to a bug.
  • A participant entity now has a parent. The "get_parent" operation no longer returns 0 for a participant because of the addition of two additional levels to the entity hierarchy: a domain, possibly containing multiple participants; and one that represents the entire library.
  • The data from a reader for a built-in topic has been extended, breaking binary compatibility.

V0.1.0 (2019-03-06)

Eclipse Cyclone DDS’ first release!

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged cyclonedds at Robotics Stack Exchange

No version for distro noetic. Known supported distros are highlighted in the buttons above.
No version for distro ardent. Known supported distros are highlighted in the buttons above.
No version for distro bouncy. Known supported distros are highlighted in the buttons above.
No version for distro crystal. Known supported distros are highlighted in the buttons above.

cyclonedds package from cyclonedds repo

cyclonedds

Package Summary

Tags No category tags.
Version 0.5.1
License Eclipse Public License 2.0
Build type CMAKE
Use RECOMMENDED

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)

Package Description

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.

Additional Links

Maintainers

  • Eclipse Foundation, Inc.

Authors

No additional authors.

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.

ThroughputThroughput

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 and FragmentSize 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.

CHANGELOG
No CHANGELOG found.

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Package Dependencies

No dependencies on ROS packages.

System Dependencies

Dependant Packages

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged cyclonedds at Robotics Stack Exchange

cyclonedds package from cyclonedds repo

cyclonedds

Package Summary

Tags No category tags.
Version 0.7.0
License Eclipse Public License 2.0
Build type CMAKE
Use RECOMMENDED

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)

Package Description

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.

Additional Links

Maintainers

  • Eclipse Foundation, Inc.

Authors

No additional authors.

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.

ThroughputThroughput

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 and FragmentSize 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.

CHANGELOG

Changelog for Eclipse Cyclone DDS

Unreleased

V0.7.0 (2020-08-06) -----------------------------------------------------------------------------------------------

This release brings support for the DDS Security 1.1 specification:authentication, access control and encryption. It also provides significant performance improvements with large samples, by better scheduling of retransmit requests and by avoiding the occasional excessive latency caused by dropping the heartbeat rate too soon.

One can choose to build Cyclone DDS without support for DDS Security if one wants to reduce the size of the resulting library. The default plug-ins are built only if security is enabled and OpenSSL is available, as those are implemented using the cryptographic operations and I/O primitives for handling certificates and exchanging keys that OpenSSL provides. If one chooses to exclude security support from the build, setting any security related property or adding it to the configuration files will result in participant creation failing with a "precondition not met" error.

A lot of effort has gone into testing and checking that malformed or unexpected messages are handled correctly, that message authentication codes are checked and that no data never goes out unencrypted by accident. Still, it is only prudent to assume the existence of vulnerabilities.

Noteworthy bug fixes:

  • DATA_AVAILABLE was not always triggered when by a dispose and sometimes triggered in the absence of an observable state change (arrival of a dispose for an already-disposed instance where the dispose had not yet been read);
  • Restores functionality of the "raw ethernet" mode as well as IPv6 with link-local addresses, both accidentally broken in 0.6.0;
  • Fixes a crash in processing endpoint discovery data containing unrecognised locator kinds;
  • Fixes type conversion for local historical data (e.g., mixed use of ROS 2 C/C++ type supports in combination with transient-local endpoints within a single process);
  • Fixes a use-after-free of "lease" objects with manual-by-topic writers;
  • Mark instance as "alive" in the reader history and generate an invalid sample to notify the application even if the sample itself is dropped because the same or a later one is present already (e.g., on reconnecting to a transient-local writer);
  • Fix a crash when doing an instance lookup on a built-in topic using the key value;
  • No longer auto-dispose instances as soon as some registered writer disappears, instead do it only when all of them have unregistered it;
  • Fix performance of read_instance and take_instance by performing a proper instance lookup.

V0.6.0 (2020-05-21) -----------------------------------------------------------------------------------------------

  • Support for mixed-language programming by supporting multiple (de)serializers for a single topic in a single process. This way, a program that consists of, say, C and C++ can use a different representation of the data in C than in C++. Before, all readers/writers in the process would be forced to use the same representation (or perform an additional copy). Currently C is still the only natively supported language, but one can use an evolving-but-reasonable-stable interface to implement different mappings.
  • Improved QoS support: full support for deadline, lifespan and liveliness. The first is for generating notifications when a configured instance update rate is not achieved, the second for automatically removing stale samples, the third for different modes of monitoring the liveliness of peers.
  • Improved scalability in matching readers and writers. Before it used to try matching a new local or remote reader or writer with all known local & remote entities, now only with the right group with the correct topic name.
  • Improved tracing: discovery data is now printed properly and user samples have more type information allowing floating-point and signed numbers to be traced in a more readable form.
  • Extension of platform support
    • Known to work on FreeBSD, CheriBSD
    • Known to work with the musl C library
  • Windows-specific changes
    • Fixes multicasts to addresses also used by non-Cyclone processes (caused by accidentally linking with an old sockets library)
    • Correct handling of non-English network interface names

0.5.1 (2020-03-11)

An interim tag for the benefit of ROS2

  • Enable QOS features: liveliness, lifespan, deadline
  • Fix issues on Windows where multicast data was not received

V0.5.0 (2019-11-21)

This is the fist release candidate for the long overdue second release of Eclipse Cyclone DDS. We are updating the version number from 0.1 to 0.5 to make up for the lack of more timely releases and to reflect that progress towards a 1.0 release (a minimum profile DDS implementation + DDS security) has been more significant than a version of "0.2" would suggest.

Updates since the first release have been legion, pretty much without impact on application code or interoperatbility on the network. Some of the highlights:

  • Support for ROS2 Dashing and Eloquent (via an adaption layer).
  • Support for an arbitrary number of concurrent DDS domains (fully independent instantiations of DDS) in a single process.
  • Abstracting the notion of samples, types and reader history caches, allowing overriding the default implementations of these to get behaviours more suited to the applications. This is particularly relevant to language bindings and embedding Cyclone DDS in other frameworks, such as ROS2.
  • Platform support is extended beyond the usual Linux/Windows/macOS: FreeRTOS is now known to work, as is Solaris 2.6 on sun4m machines.
  • Acceptance of some malformed messages from certain implementations improved interoperability on the wire.

Limitations on backwards compatibility:

  • A change in how implicitly created "publisher" and "subscriber" entities are handled: they now never lose their "implicitness", and in consequence, are now deleted when their last child disappears rather than deleted when their one child disappears.
  • The set of entities that can be attached to a waitset is now restricted to those owned by the parent of the waitset, before one was allowed to attach entities from different participants to the same waitset, which is tantamount to a bug.
  • A participant entity now has a parent. The "get_parent" operation no longer returns 0 for a participant because of the addition of two additional levels to the entity hierarchy: a domain, possibly containing multiple participants; and one that represents the entire library.
  • The data from a reader for a built-in topic has been extended, breaking binary compatibility.

V0.1.0 (2019-03-06)

Eclipse Cyclone DDS’ first release!

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Package Dependencies

No dependencies on ROS packages.

System Dependencies

Dependant Packages

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged cyclonedds at Robotics Stack Exchange

cyclonedds package from cyclonedds repo

cyclonedds

Package Summary

Tags No category tags.
Version 0.8.2
License Eclipse Public License 2.0
Build type CMAKE
Use RECOMMENDED

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)

Package Description

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.

Additional Links

Maintainers

  • Eclipse Foundation, Inc.

Authors

No additional authors.

Build Status Coverity Status Coverage License License

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.

ThroughputThroughput

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 and FragmentSize 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.

CHANGELOG

Changelog for Eclipse Cyclone DDS

Unreleased

V0.7.0 (2020-08-06) -----------------------------------------------------------------------------------------------

This release brings support for the DDS Security 1.1 specification:authentication, access control and encryption. It also provides significant performance improvements with large samples, by better scheduling of retransmit requests and by avoiding the occasional excessive latency caused by dropping the heartbeat rate too soon.

One can choose to build Cyclone DDS without support for DDS Security if one wants to reduce the size of the resulting library. The default plug-ins are built only if security is enabled and OpenSSL is available, as those are implemented using the cryptographic operations and I/O primitives for handling certificates and exchanging keys that OpenSSL provides. If one chooses to exclude security support from the build, setting any security related property or adding it to the configuration files will result in participant creation failing with a "precondition not met" error.

A lot of effort has gone into testing and checking that malformed or unexpected messages are handled correctly, that message authentication codes are checked and that no data never goes out unencrypted by accident. Still, it is only prudent to assume the existence of vulnerabilities.

Noteworthy bug fixes:

  • DATA_AVAILABLE was not always triggered when by a dispose and sometimes triggered in the absence of an observable state change (arrival of a dispose for an already-disposed instance where the dispose had not yet been read);
  • Restores functionality of the "raw ethernet" mode as well as IPv6 with link-local addresses, both accidentally broken in 0.6.0;
  • Fixes a crash in processing endpoint discovery data containing unrecognised locator kinds;
  • Fixes type conversion for local historical data (e.g., mixed use of ROS 2 C/C++ type supports in combination with transient-local endpoints within a single process);
  • Fixes a use-after-free of "lease" objects with manual-by-topic writers;
  • Mark instance as "alive" in the reader history and generate an invalid sample to notify the application even if the sample itself is dropped because the same or a later one is present already (e.g., on reconnecting to a transient-local writer);
  • Fix a crash when doing an instance lookup on a built-in topic using the key value;
  • No longer auto-dispose instances as soon as some registered writer disappears, instead do it only when all of them have unregistered it;
  • Fix performance of read_instance and take_instance by performing a proper instance lookup.

V0.6.0 (2020-05-21) -----------------------------------------------------------------------------------------------

  • Support for mixed-language programming by supporting multiple (de)serializers for a single topic in a single process. This way, a program that consists of, say, C and C++ can use a different representation of the data in C than in C++. Before, all readers/writers in the process would be forced to use the same representation (or perform an additional copy). Currently C is still the only natively supported language, but one can use an evolving-but-reasonable-stable interface to implement different mappings.
  • Improved QoS support: full support for deadline, lifespan and liveliness. The first is for generating notifications when a configured instance update rate is not achieved, the second for automatically removing stale samples, the third for different modes of monitoring the liveliness of peers.
  • Improved scalability in matching readers and writers. Before it used to try matching a new local or remote reader or writer with all known local & remote entities, now only with the right group with the correct topic name.
  • Improved tracing: discovery data is now printed properly and user samples have more type information allowing floating-point and signed numbers to be traced in a more readable form.
  • Extension of platform support
    • Known to work on FreeBSD, CheriBSD
    • Known to work with the musl C library
  • Windows-specific changes
    • Fixes multicasts to addresses also used by non-Cyclone processes (caused by accidentally linking with an old sockets library)
    • Correct handling of non-English network interface names

0.5.1 (2020-03-11)

An interim tag for the benefit of ROS2

  • Enable QOS features: liveliness, lifespan, deadline
  • Fix issues on Windows where multicast data was not received

V0.5.0 (2019-11-21)

This is the fist release candidate for the long overdue second release of Eclipse Cyclone DDS. We are updating the version number from 0.1 to 0.5 to make up for the lack of more timely releases and to reflect that progress towards a 1.0 release (a minimum profile DDS implementation + DDS security) has been more significant than a version of "0.2" would suggest.

Updates since the first release have been legion, pretty much without impact on application code or interoperatbility on the network. Some of the highlights:

  • Support for ROS2 Dashing and Eloquent (via an adaption layer).
  • Support for an arbitrary number of concurrent DDS domains (fully independent instantiations of DDS) in a single process.
  • Abstracting the notion of samples, types and reader history caches, allowing overriding the default implementations of these to get behaviours more suited to the applications. This is particularly relevant to language bindings and embedding Cyclone DDS in other frameworks, such as ROS2.
  • Platform support is extended beyond the usual Linux/Windows/macOS: FreeRTOS is now known to work, as is Solaris 2.6 on sun4m machines.
  • Acceptance of some malformed messages from certain implementations improved interoperability on the wire.

Limitations on backwards compatibility:

  • A change in how implicitly created "publisher" and "subscriber" entities are handled: they now never lose their "implicitness", and in consequence, are now deleted when their last child disappears rather than deleted when their one child disappears.
  • The set of entities that can be attached to a waitset is now restricted to those owned by the parent of the waitset, before one was allowed to attach entities from different participants to the same waitset, which is tantamount to a bug.
  • A participant entity now has a parent. The "get_parent" operation no longer returns 0 for a participant because of the addition of two additional levels to the entity hierarchy: a domain, possibly containing multiple participants; and one that represents the entire library.
  • The data from a reader for a built-in topic has been extended, breaking binary compatibility.

V0.1.0 (2019-03-06)

Eclipse Cyclone DDS’ first release!

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged cyclonedds at Robotics Stack Exchange

cyclonedds package from cyclonedds repo

cyclonedds

Package Summary

Tags No category tags.
Version 0.7.0
License Eclipse Public License 2.0
Build type CMAKE
Use RECOMMENDED

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)

Package Description

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.

Additional Links

Maintainers

  • Eclipse Foundation, Inc.

Authors

No additional authors.

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.

ThroughputThroughput

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 and FragmentSize 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.

CHANGELOG

Changelog for Eclipse Cyclone DDS

Unreleased

V0.7.0 (2020-08-06) -----------------------------------------------------------------------------------------------

This release brings support for the DDS Security 1.1 specification:authentication, access control and encryption. It also provides significant performance improvements with large samples, by better scheduling of retransmit requests and by avoiding the occasional excessive latency caused by dropping the heartbeat rate too soon.

One can choose to build Cyclone DDS without support for DDS Security if one wants to reduce the size of the resulting library. The default plug-ins are built only if security is enabled and OpenSSL is available, as those are implemented using the cryptographic operations and I/O primitives for handling certificates and exchanging keys that OpenSSL provides. If one chooses to exclude security support from the build, setting any security related property or adding it to the configuration files will result in participant creation failing with a "precondition not met" error.

A lot of effort has gone into testing and checking that malformed or unexpected messages are handled correctly, that message authentication codes are checked and that no data never goes out unencrypted by accident. Still, it is only prudent to assume the existence of vulnerabilities.

Noteworthy bug fixes:

  • DATA_AVAILABLE was not always triggered when by a dispose and sometimes triggered in the absence of an observable state change (arrival of a dispose for an already-disposed instance where the dispose had not yet been read);
  • Restores functionality of the "raw ethernet" mode as well as IPv6 with link-local addresses, both accidentally broken in 0.6.0;
  • Fixes a crash in processing endpoint discovery data containing unrecognised locator kinds;
  • Fixes type conversion for local historical data (e.g., mixed use of ROS 2 C/C++ type supports in combination with transient-local endpoints within a single process);
  • Fixes a use-after-free of "lease" objects with manual-by-topic writers;
  • Mark instance as "alive" in the reader history and generate an invalid sample to notify the application even if the sample itself is dropped because the same or a later one is present already (e.g., on reconnecting to a transient-local writer);
  • Fix a crash when doing an instance lookup on a built-in topic using the key value;
  • No longer auto-dispose instances as soon as some registered writer disappears, instead do it only when all of them have unregistered it;
  • Fix performance of read_instance and take_instance by performing a proper instance lookup.

V0.6.0 (2020-05-21) -----------------------------------------------------------------------------------------------

  • Support for mixed-language programming by supporting multiple (de)serializers for a single topic in a single process. This way, a program that consists of, say, C and C++ can use a different representation of the data in C than in C++. Before, all readers/writers in the process would be forced to use the same representation (or perform an additional copy). Currently C is still the only natively supported language, but one can use an evolving-but-reasonable-stable interface to implement different mappings.
  • Improved QoS support: full support for deadline, lifespan and liveliness. The first is for generating notifications when a configured instance update rate is not achieved, the second for automatically removing stale samples, the third for different modes of monitoring the liveliness of peers.
  • Improved scalability in matching readers and writers. Before it used to try matching a new local or remote reader or writer with all known local & remote entities, now only with the right group with the correct topic name.
  • Improved tracing: discovery data is now printed properly and user samples have more type information allowing floating-point and signed numbers to be traced in a more readable form.
  • Extension of platform support
    • Known to work on FreeBSD, CheriBSD
    • Known to work with the musl C library
  • Windows-specific changes
    • Fixes multicasts to addresses also used by non-Cyclone processes (caused by accidentally linking with an old sockets library)
    • Correct handling of non-English network interface names

0.5.1 (2020-03-11)

An interim tag for the benefit of ROS2

  • Enable QOS features: liveliness, lifespan, deadline
  • Fix issues on Windows where multicast data was not received

V0.5.0 (2019-11-21)

This is the fist release candidate for the long overdue second release of Eclipse Cyclone DDS. We are updating the version number from 0.1 to 0.5 to make up for the lack of more timely releases and to reflect that progress towards a 1.0 release (a minimum profile DDS implementation + DDS security) has been more significant than a version of "0.2" would suggest.

Updates since the first release have been legion, pretty much without impact on application code or interoperatbility on the network. Some of the highlights:

  • Support for ROS2 Dashing and Eloquent (via an adaption layer).
  • Support for an arbitrary number of concurrent DDS domains (fully independent instantiations of DDS) in a single process.
  • Abstracting the notion of samples, types and reader history caches, allowing overriding the default implementations of these to get behaviours more suited to the applications. This is particularly relevant to language bindings and embedding Cyclone DDS in other frameworks, such as ROS2.
  • Platform support is extended beyond the usual Linux/Windows/macOS: FreeRTOS is now known to work, as is Solaris 2.6 on sun4m machines.
  • Acceptance of some malformed messages from certain implementations improved interoperability on the wire.

Limitations on backwards compatibility:

  • A change in how implicitly created "publisher" and "subscriber" entities are handled: they now never lose their "implicitness", and in consequence, are now deleted when their last child disappears rather than deleted when their one child disappears.
  • The set of entities that can be attached to a waitset is now restricted to those owned by the parent of the waitset, before one was allowed to attach entities from different participants to the same waitset, which is tantamount to a bug.
  • A participant entity now has a parent. The "get_parent" operation no longer returns 0 for a participant because of the addition of two additional levels to the entity hierarchy: a domain, possibly containing multiple participants; and one that represents the entire library.
  • The data from a reader for a built-in topic has been extended, breaking binary compatibility.

V0.1.0 (2019-03-06)

Eclipse Cyclone DDS’ first release!

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Package Dependencies

No dependencies on ROS packages.

System Dependencies

Dependant Packages

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged cyclonedds at Robotics Stack Exchange

cyclonedds package from cyclonedds repo

cyclonedds

Package Summary

Tags No category tags.
Version 0.10.5
License Eclipse Public License 2.0
Build type CMAKE
Use RECOMMENDED

Repository Summary

Checkout URI https://github.com/eclipse-cyclonedds/cyclonedds.git
VCS Type git
VCS Version releases/0.10.x
Last Updated 2024-11-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)

Package Description

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.

Additional Links

Maintainers

  • Eclipse Foundation, Inc.

Authors

No additional authors.

GitHub release Build Status Coverity Status Coverage License License Website Community

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 and ddsperf)
  • -DBUILD_DDSPERF=NO: to disable building the ddsperf tool for performance measurement
  • -DENABLE_SSL=NO: to not look for OpenSSL, remove TLS/TCP support and avoid building the plugins that implement authentication and encryption (default is AUTO to enable them if OpenSSL is found)
  • -DENABLE_SHM=NO: to not look for Iceoryx and disabled shared memory support (default is AUTO to enable it if Iceoryx is found)
  • -DENABLE_SECURITY=NO: to not build the security interfaces and hooks in the core code, nor the plugins (one can enable security without OpenSSL present, you’ll just have to find plugins elsewhere in that case)
  • -DENABLE_LIFESPAN=NO: to exclude support for finite lifespans QoS
  • -DENABLE_DEADLINE_MISSED=NO: to exclude support for finite deadline QoS settings
  • -DENABLE_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.

ThroughputThroughput

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 priority 0 for normal interfaces and 2 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.
CHANGELOG

Changelog for Eclipse Cyclone DDS

Unreleased

V0.7.0 (2020-08-06) -----------------------------------------------------------------------------------------------

This release brings support for the DDS Security 1.1 specification:authentication, access control and encryption. It also provides significant performance improvements with large samples, by better scheduling of retransmit requests and by avoiding the occasional excessive latency caused by dropping the heartbeat rate too soon.

One can choose to build Cyclone DDS without support for DDS Security if one wants to reduce the size of the resulting library. The default plug-ins are built only if security is enabled and OpenSSL is available, as those are implemented using the cryptographic operations and I/O primitives for handling certificates and exchanging keys that OpenSSL provides. If one chooses to exclude security support from the build, setting any security related property or adding it to the configuration files will result in participant creation failing with a "precondition not met" error.

A lot of effort has gone into testing and checking that malformed or unexpected messages are handled correctly, that message authentication codes are checked and that no data never goes out unencrypted by accident. Still, it is only prudent to assume the existence of vulnerabilities.

Noteworthy bug fixes:

  • DATA_AVAILABLE was not always triggered when by a dispose and sometimes triggered in the absence of an observable state change (arrival of a dispose for an already-disposed instance where the dispose had not yet been read);
  • Restores functionality of the "raw ethernet" mode as well as IPv6 with link-local addresses, both accidentally broken in 0.6.0;
  • Fixes a crash in processing endpoint discovery data containing unrecognised locator kinds;
  • Fixes type conversion for local historical data (e.g., mixed use of ROS 2 C/C++ type supports in combination with transient-local endpoints within a single process);
  • Fixes a use-after-free of "lease" objects with manual-by-topic writers;
  • Mark instance as "alive" in the reader history and generate an invalid sample to notify the application even if the sample itself is dropped because the same or a later one is present already (e.g., on reconnecting to a transient-local writer);
  • Fix a crash when doing an instance lookup on a built-in topic using the key value;
  • No longer auto-dispose instances as soon as some registered writer disappears, instead do it only when all of them have unregistered it;
  • Fix performance of read_instance and take_instance by performing a proper instance lookup.

V0.6.0 (2020-05-21) -----------------------------------------------------------------------------------------------

  • Support for mixed-language programming by supporting multiple (de)serializers for a single topic in a single process. This way, a program that consists of, say, C and C++ can use a different representation of the data in C than in C++. Before, all readers/writers in the process would be forced to use the same representation (or perform an additional copy). Currently C is still the only natively supported language, but one can use an evolving-but-reasonable-stable interface to implement different mappings.
  • Improved QoS support: full support for deadline, lifespan and liveliness. The first is for generating notifications when a configured instance update rate is not achieved, the second for automatically removing stale samples, the third for different modes of monitoring the liveliness of peers.
  • Improved scalability in matching readers and writers. Before it used to try matching a new local or remote reader or writer with all known local & remote entities, now only with the right group with the correct topic name.
  • Improved tracing: discovery data is now printed properly and user samples have more type information allowing floating-point and signed numbers to be traced in a more readable form.
  • Extension of platform support
    • Known to work on FreeBSD, CheriBSD
    • Known to work with the musl C library
  • Windows-specific changes
    • Fixes multicasts to addresses also used by non-Cyclone processes (caused by accidentally linking with an old sockets library)
    • Correct handling of non-English network interface names

0.5.1 (2020-03-11)

An interim tag for the benefit of ROS2

  • Enable QOS features: liveliness, lifespan, deadline
  • Fix issues on Windows where multicast data was not received

V0.5.0 (2019-11-21)

This is the fist release candidate for the long overdue second release of Eclipse Cyclone DDS. We are updating the version number from 0.1 to 0.5 to make up for the lack of more timely releases and to reflect that progress towards a 1.0 release (a minimum profile DDS implementation + DDS security) has been more significant than a version of "0.2" would suggest.

Updates since the first release have been legion, pretty much without impact on application code or interoperatbility on the network. Some of the highlights:

  • Support for ROS2 Dashing and Eloquent (via an adaption layer).
  • Support for an arbitrary number of concurrent DDS domains (fully independent instantiations of DDS) in a single process.
  • Abstracting the notion of samples, types and reader history caches, allowing overriding the default implementations of these to get behaviours more suited to the applications. This is particularly relevant to language bindings and embedding Cyclone DDS in other frameworks, such as ROS2.
  • Platform support is extended beyond the usual Linux/Windows/macOS: FreeRTOS is now known to work, as is Solaris 2.6 on sun4m machines.
  • Acceptance of some malformed messages from certain implementations improved interoperability on the wire.

Limitations on backwards compatibility:

  • A change in how implicitly created "publisher" and "subscriber" entities are handled: they now never lose their "implicitness", and in consequence, are now deleted when their last child disappears rather than deleted when their one child disappears.
  • The set of entities that can be attached to a waitset is now restricted to those owned by the parent of the waitset, before one was allowed to attach entities from different participants to the same waitset, which is tantamount to a bug.
  • A participant entity now has a parent. The "get_parent" operation no longer returns 0 for a participant because of the addition of two additional levels to the entity hierarchy: a domain, possibly containing multiple participants; and one that represents the entire library.
  • The data from a reader for a built-in topic has been extended, breaking binary compatibility.

V0.1.0 (2019-03-06)

Eclipse Cyclone DDS’ first release!

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Dependant Packages

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged cyclonedds at Robotics Stack Exchange

No version for distro lunar. Known supported distros are highlighted in the buttons above.
No version for distro jade. Known supported distros are highlighted in the buttons above.
No version for distro indigo. Known supported distros are highlighted in the buttons above.
No version for distro hydro. Known supported distros are highlighted in the buttons above.
No version for distro kinetic. Known supported distros are highlighted in the buttons above.
No version for distro melodic. Known supported distros are highlighted in the buttons above.