Expand description
A pure Rust implementation of Data Distribution Service (DDS).
DDS is an object-oriented API specified by the Object Management Group.
DDS communicates over the network using the RTPS protocol, which by default runs over UDP/IP.
This implementation does not attempt to make an accurate implementation of the DDS object API, as it would be quite unnatural to use in Rust as such. However, we aim for functional compatibility, while at the same time using Rust techniques and conventions.
Additionally, there is a ROS2 interface, that is simpler to use than DDS when communicating to ROS2 components.
DDS usage summary
- Create a
DomainParticipant. You have to choose a domain id. The default value is zero. - Create or find a
Topicfrom theDomainParticipant. Topics have a name and a type. - Create a
Publisherand/orSubscriberfrom theDomainParticipant. - To receive data, create a
DataReaderfromSubscriberandTopic. - To send data, create a
DataWriterfromPublisherandTopic. - Data from
DataReadercan be read or taken. Taking removes the data samples from the DataReader, whereas reading only marks them as read.
Concepts
- Data is sent and received in consecutive samples. When read, a sample is
accompanied with
SampleInfo, which contains DDS-generated metadata. - Topics are either With_Key or No_Key.
- With_Key topics are like map data structures, containing multiple instances (map entries), identified by a key. The key must be something that can be extracted from the data samples. Instances can be created (published) and deleted (disposed).
- No_Key topics have always only one instance, which cannot be disposed.
- Many types and traits in RustDDS have both with_key and no_key versions. This is because with_key communication must be able to access keys from data samples, so it is required in type signatures. Such requirement makes no sense for no_key communication, so signature must be different.
Interfacing Rust data types to DDS
- DDS, as specified, takes care of data serialization and deserialization. In order for RustDDS to do this, the payload data must be Serde serializable/deserializable.
- If your data is to be communicated over a WithKey topic, the payload data
type must implement
Keyedtrait from this crate. - If you are using CDR serialization
(specification, Section 15.3) , which
is the DDS default, then use
CDRSerializerAdapterandCDRDeserializerAdapterwhen such adapters are required. If you need to use another serialization format, then you should find or write a Serde data format implementation and wrap it as a (De)SerializerAdaper.
Polling multiple DataReaders
RustDDS is designed to used with mio version 0.6.x. DataReaders
implement Evented so that they can be directly
registered to a poll.
Usage Example
use rustdds::*;
use rustdds::no_key::{DataReader, DataWriter, DataSample}; // We use a NO_KEY topic here
use serde::{Serialize, Deserialize};
// DomainParticipant is always necessary
let domain_participant = DomainParticipant::new(0).unwrap();
let qos = QosPolicyBuilder::new()
.reliability(policy::Reliability::Reliable { max_blocking_time: rustdds::Duration::DURATION_ZERO })
.build();
// DDS Subscriber, only one is necessary for each thread (slight difference to
// DDS specification)
let subscriber = domain_participant.create_subscriber(&qos).unwrap();
// DDS Publisher, only one is necessary for each thread (slight difference to
// DDS specification)
let publisher = domain_participant.create_publisher(&qos).unwrap();
// Some DDS Topic that we can write and read from (basically only binds readers
// and writers together)
let some_topic = domain_participant.create_topic("some_topic".to_string(), "SomeType".to_string(), &qos, TopicKind::NoKey).unwrap();
// Used type needs Serialize for writers and Deserialize for readers
#[derive(Serialize, Deserialize)]
struct SomeType {
a: i32
}
// Creating DataReader requires type and deserializer adapter (which is recommended to be CDR).
// Reader needs to be mutable if any operations are used.
let mut reader = subscriber
.create_datareader_no_key::<SomeType, CDRDeserializerAdapter<SomeType>>(
&some_topic,
None)
.unwrap();
// Creating DataWriter required type and serializer adapter (which is recommended to be CDR).
let writer = publisher
.create_datawriter_no_key::<SomeType, CDRSerializerAdapter<SomeType>>(
&some_topic,
None)
.unwrap();
// Readers implement mio Evented trait and thus function the same way as
// std::sync::mpcs and can be handled the same way for reading the data
let some_data = SomeType { a: 1 };
// This should send the data to all who listen "some_topic" topic.
writer.write(some_data, None).unwrap();
// ... Some data has arrived at some point for the reader
let data_sample = if let Ok(Some(value)) = reader.read_next_sample() {
value
} else {
// no data has arrived
return;
};
// Getting reference to actual data from the data sample
let actual_data = data_sample.value();Modules
Components used to access NO_KEY Topics
Contains all available QoSPolicies
DDS Quality of Service
ROS2 interface using DDS module
Helpers for (De)serialization and definitions of (De)serializer adapters
Components used to access WITH_KEY Topics
Structs
This type adapts CdrDeserializer (which implements serde::Deserializer) to
work as a with_key::DeserializerAdapter and
no_key::DeserializerAdapter.
This type adapts CdrSerializer (which implements
serde::Serializer) to work as a no_key::SerializerAdapter and
with_key::SerializerAdapter.
a CDR deserializer implementation.
a CDR deserializer implementation
DDS DomainParticipant
Duration is the DDS/RTPS representation for legths of time, such as
timeouts. It is very similar to std::time::Duration. See also
Timestamp.
DDS/RTPS GUID
A double counter for counting how many times an instance as become Alive.
DDS Publisher
Describes a set of RTPS/DDS QoS policies
Utility for building QosPolicies
This is used to specify which samples are to be read or taken from
a Datareader
Used to identify serialization format of payload data over RTPS.
SampleInfo is metadata attached to each received data sample. It exists only at the receiving end of DDS, and is (mostly) generated by DDS.
RTPS Specification v2.3 Section “8.3.5.4 SequenceNumber”
DDS Subscriber
Representation of time instants in DDS API and RTPS protocol. Similar to
std::time::Instant.
DDS Topic
Type to be used with write_with_options. Use WriteOptionsBuilder to construct this.
Enums
Is this data instance alive or not and why.
indicates whether or not the corresponding data sample has already
been read by this DataReader.
Type for DDS Topic (With Key or No key)
Indicates if this data instance has been seen (viewed).
Traits
Trait for instance lookup key in a WITH_KEY topic.
Trait for things that have a GUID.
This trait corresponds to set_listener() of the Entity class in DDS spec. Types implementing this trait can be registered to a poll and polled for status events.
Trait approximation of DDS 2.2.2.3.1 TopicDescription Class