rmw_cyclonedds

The rmw_cyclonedds_cpp package is classified as Quality Level 2.

Public API

The public API is declared through the rmw package. Documentation for the public API is generated using Doxygen and is hosted alongside the feature documentation in the official ROS 2 API docs.

Stability Guarantees

• API Stability: The package guarantees that it will not break the public API within a released ROS distribution (no major releases once a distribution is released).
• ABI Stability: The package maintains ABI stability within a ROS distribution for both its C and C++ code.

CycloneDDS Insight is a graphical tool used to:

• Inspect participants, topics, publishers, and subscribers.
• Diagnose discovery issues.
• Verify communication architectures.
• Monitor DDS traffic statistics (received bytes, sent bytes, and retransmitted bytes).

To use Eclipse Cyclone DDS as your ROS 2 middleware, install the appropriate package for your ROS 2 distribution and set the RMW_IMPLEMENTATION environment variable.

1. Installation

Install via apt depending on your ROS 2 version:

• For Eloquent: apt install ros-eloquent-rmw-cyclonedds-cpp
• For Dashing: apt install ros-dashing-rmw-cyclonedds-cpp

2. Activation

Set the environment variable in your terminal before running ROS 2 applications:

export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

3. Verification

To confirm which RMW implementation is currently active, use the ROS 2 doctor tool:

ros2 doctor --report

When working with large samples (hundreds of kilobytes), you may experience excessive latency due to OS-level receive buffer exhaustion. On Linux, increase the net.core.rmem_max and net.core.rmem_default values.

Temporary change (until reboot):

sudo sysctl -w net.core.rmem_max=8388608 net.core.rmem_default=8388608

Permanent change: Create a configuration file in /etc/sysctl.d/:

echo "net.core.rmem_max=8388608\nnet.core.rmem_default=8388608\n" | sudo tee /etc/sysctl.d/60-cyclonedds.conf

The ddsperf tool (distributed with Cyclone DDS) allows you to verify that the DDS layer is functioning correctly independently of ROS 2.

Run the following command on two different machines:

ddsperf sanity

Interpretation: If the reported "mean" value is greater than 100000us, there are likely underlying network issues.

The package supports all Tier 1 ROS platforms. Nightly CI results are available for the following platforms:

• linux-aarch64 (release)
• linux (release)
• mac_osx (release)
• windows (release)

To use rmw_cyclonedds_cpp, the following runtime dependencies must be present in your environment:

ROS Dependencies

• rcpputils
• rcutils
• rmw
• rmw_dds_common
• rosidl_runtime_c
• rosidl_runtime_cpp
• rosidl_typesupport_introspection_c
• rosidl_typesupport_introspection_cpp
• tracetools

Non-ROS Dependencies

• cyclonedds (Eclipse Cyclone DDS)

The BaseCDRWriter interface provides the following methods for managing serialization:

• get_serialized_size(const void * data, SampleOrKey what): Returns the exact size required to serialize the data.
• get_serialized_size_estimate(const void * data, SampleOrKey what): Returns an estimated size for serialization.
• get_min_serialized_size(SampleOrKey what): Returns the minimum size, including a 4-byte encoding header.
• get_max_serialized_size(SampleOrKey what): Returns the maximum size, including a 4-byte encoding header (returns SIZE_MAX if the type is unbounded).
• serialize(void * dest, const void * data, SampleOrKey what): Performs the actual serialization of data into the dest buffer.

Use make_cdr_reader to instantiate a BaseCDRReader for a specific type. This reader allows you to deserialize CDR-encoded data back into a destination structure, extract keys, or print the contents of the CDR buffer for debugging.

// Example usage pattern
std::unique_ptr<BaseCDRReader> reader = make_cdr_reader(value_type, SampleOrRequest::Sample);

reader->deserialize(dest, cdr_buffer, cdr_size, SampleOrKey::Sample);

Use make_cdr_writer to instantiate a BaseCDRWriter for a specific type. This writer provides methods to calculate the required buffer size and perform the actual serialization of data into Common Data Representation (CDR) format.

Supported variants for the variant parameter include:

• SampleOrRequest::Sample
• SampleOrRequest::Request

// Example usage pattern
std::unique_ptr<BaseCDRWriter> writer = make_cdr_writer(value_type, SampleOrRequest::Sample);

size_t size = writer->get_serialized_size(data, SampleOrKey::Sample);
// ... allocate buffer ...
writer->serialize(buffer, data, SampleOrKey::Sample);

The BaseCDRReader interface provides the following methods for handling CDR data:

• deserialize(void * dest, const void * cdr, size_t cdrsize, SampleOrKey what): Deserializes the CDR buffer into the dest pointer.
• extractkey(std::vector<byte> & dest, const void * cdr, size_t cdrsize, SampleOrKey what): Extracts the key from the CDR buffer into a byte vector.
• extractkey_be(std::vector<byte> & dst, const void * cdr, size_t cdrsize, SampleOrKey what): Extracts the key from the CDR buffer using Big Endian format.
• print(char * dst, size_t dstsize, const void * cdr, size_t cdrsize, SampleOrKey what): Formats the CDR content as a string into dst for debugging purposes.