eProsima Fast RTPS Documentation¶

Boost Libraries¶

The Windows installer version provides the necessary boost binaries and headers. If you are using Linux or compiling from source you will need to install version 1.61

Gtest¶

Gtest is needed to compile the tests when building from sources.

Java¶

Java is required to make use of our buil-in code generation tool fastrtpsgen.

Visual C++ 2013 or 2015 Redistributable Package¶

eProsima Fast RTPS requires the Visual C++ Redistributable packages for the Visual Studio version you choose during the installation or compilation. The installer gives you the option of downloading and installing them.

Environmental Variables¶

eProsima Fast RTPS requires the following environmental variable setup in order to function properly

• FASTRTPSHOME: Root folder where eProsima Fast RTPS is installed.
• Additions to the PATH: the /bin folder and the subfolder for your Visual Studio version of choice should be appended to the PATH.

These variables are set automatically by checking the corresponding box during the installation process.

Threads¶

eProsima Fast RTPS is concurrent and event-based. Each participant spawns a set of threads to take care of background tasks such as logging, message reception and asynchronous communication. This should not impact the way you use the library: the public API is thread safe, so you can fearlessly call any methods on the same participant from different threads. However, it is still useful to know how Fast RTPS schedules work:

• Main thread: Managed by the application.
• Event thread: Each participant owns one of these, and it processes periodic and triggered events.
• Asynchronous writer thread: This thread manages asynchronous writes for all participants. Even for synchronous writers, some forms of communication must be initiated in the background.
• Reception threads: Participants spawn a thread for each reception channel, where the concept of channel depends on the transport layer (e.g. an UDP port).

Events¶

There is an event system that enables Fast RTPS to respond to certain conditions, as well as schedule periodic activities. Few of them are visible to the user, since most are related to RTPS metadata. However, you can define your own periodic events by inheriting from the TimedEvent class.

RTPS Common¶

• CacheChange_t Represents a change to a topic, to be stored in a history cache.
• Data Payload associated to a cache change. May be empty depending on the message and change type.
• Message Defines the organization of a RTPS Message.
• Header Standard header that identifies a message as belonging to the RTPS protocol, and includes the vendor id.
• Sub-Message Header Identifier for an RTPS sub-message. An RTPS Message can be composed of several sub-messages.
• MessageReceiver Deserializes and processes received RTPS messages.
• RTPSMessageCreator Composes RTPS messages.

RTPS Domain¶

• RTPSDomain Use it to create, manage and destroy low-level RTPSParticipants.

• RTPSParticipant Contains RTPS Writers and Readers, and manages their configuration.

  • RTPSParticipantAttributes Configuration parameters used in the creation of an RTPS Participant.
  • PDPSimple Allows the participant to become aware of the other participants within the Network, through the Participant Discovery Protocol.
  • EDPSimple Allows the Participant to become aware of the endpoints (RTPS Writers and Readers) present in the other Participants within the network, through the Endpoint Discovery Protocol.
  • EDPStatic Reads information about remote endpoints from a user file.
  • TimedEvent Base class for periodic or timed events.

RTPS Reader¶

• RTPSReader Base class for the reader endpoint.

  • ReaderAttributes Configuration parameters used in the creation of an RTPS Reader.
  • ReaderHistory History data structure. Stores recent topic changes.
  • ReaderListener Use it to define callbacks in scope of the Reader.

RTPS Writer¶

• RTPSWriter Base class for the writer endpoint.

  • WriterAttributes Configuration parameters used in the creation of an RTPS Writer.
  • WriterHistory History data structure. Stores outgoing topic changes and schedules them to be sent.

Setting the name and Domain of the Participant¶

The name of the Participant, which forms part of the meta-data of the RTPS protocol, can be changed from within the ParticipantAttributes:

Pparam.setName("my_participant");

Publishers and Subscribers can only talk to each other if their Participants belong to the same DomainId. To set the Domain:

Pparam.rtps.builtin.domainId = 80;

Defining Input and Output channels¶

In the RTPS Standard, input-output channels (sockets) are defined as Locators. Locators in eprosima Fast RTPS are enclosed as type Locator_t, which has the following fields:

• Kind: Defines the protocol. eProsima Fast RTPS currently supports UDPv4 or UDPv6
• Port: Port as an UDP/IP port.
• Address: Maps to IP address.

You can specify a default list of channels for the Publishers and Subscribers by passing lists of Locators to the configuration structure

Locator_t loc1.set_IP4_address(127,0,0,1);
loc1.port = 22222;
Pparam.rtps.defaultUnicastLocatorList.push_back(loc1); //Input for Unicast messages
Locator_t loc2.set_IP4_address(127,0,0,1);
loc2.port = 33333;
Pparam.rtps.defaultMulticastLocatorList.push_back(loc2); //Input for Multicast messages
Locator_t loc3.set_IP4_address(127,0,0,1);
loc3.port = 44444;
Pparam.rtps.defaultOutLocatorList.push_back(loc3); //Output Channels

If no Locators are specified by the user eprosima Fast RTPS will calculate a minimalistic set to ensure correct behaviour.

Setting the name and data type of the topic¶

The topic name and data type are used as meta-data to determine whether Publishers and Subscribers can exchange messages.

// Topic name and type for Publisher
Wparam.topic.topicDataType = "HelloWorldType"
Wparam.topic.topicName = "HelloWorldTopic"
// Topic name and type for Subscriber
Rparam.topic.topicName = "HelloWorldTopic"
Rparam.topic.topicDataType = "HelloWorldType"

Reliability Kind¶

The RTPS standard defines two behaviour modes for message delivery:

• Best-Effort (default): Messages are sent without arrival confirmation from the receiver (subscriber). It is fast, but messages can be lost.
• Reliable: The sender agent (publisher) expects arrival confirmation from the receiver (subscriber). It is slower, but prevents data loss.

You can specify which mode you want to use in the publisher or subscriber parameters:

Wparam.qos.m_reliability.kind = RELIABLE_RELIABILITY_QOS; //Set the publisher to Realiable Mode
Rparam.qos.m_reliability.kind = BEST_EFFORT_RELIABILITY_QOS; //Set the subscriber to Best Effort

Keep in mind that different reliability mode configurations will make a Publisher and a Subscriber incompatible and unable to talk to each other. Read more about this in the [Built-In Prococols](#built-in-procotols) section.

Configuring sample storage¶

eProsima Fast RTPS provides two policies for sample storage:

• Keep-All (Default): Store all samples in memory.
• Keep-Last: Store samples up to a maximum depth. When this limit is reached, they start to become overwritten.

The mode is changed the following way:

Wparam.topic.historyQos.kind = KEEP_LAST;

The depth of the stored samples in keep-last mode is changes in the following way:

Wparam.topic.historyQos.depth = 5; //changes the maximum number of stored samples

The durability configuration of the endpoint defines how it behaves regarding samples that existed on the topic before a Subscriber joins

• Volatile: Past samples are ignored, a joining Subscriber receives samples generated after the moment it matches.
• Transient Local (Default): When a new Subscriber joins, its History is filled with past samples.

To set the durability mode:

Rparam.qos.m_durability.kind = VOLATILE_DURABILITY_QOS;

It is also possible to control the maximum size of the History:

Built-In Protocols¶

Before a Publisher and a Subscriber can exchange messages, they must be matched. The matching process is performed by the built-in protocols.

The RTPS Standard defines two built-in protocols that are used by Endpoints to gain information about other elements in the network

• Participant Discovery Protocol (PDP): Used by the Participant to gain knowledge of other Participants in the network.
• Endpoint Discovery Protocol (EDP): Used to gain knowledge of the endpoints (Publishers and Subscribers) a remote Participant has.

When a local and a remote endpoint have the same topic name, data type and have compatible configuration they are matched and data posted by Publisher is delivered to the Subscriber. When a Publisher posts data it is sent to all of its matching Subscribers. This includes the exchange arrival confirmation messages from both parties in the case of Reliable Mode.

As an user, you can actually interact with the way the Built-in protocols behave. To learn more, go to the [Advanced Topics](#Advanced Topics) section.

Using message meta-data¶

When a message is taken from the Subscriber, an auxiliary SampleInfo_t structure instance is also returned.

HelloWorld m_Hello;
SampleInfo_t m_info;
sub->takeNextData((void*)&m_Hello, &m_info);

This SampleInfo_t structure contains meta-data on the incoming message:

• sampleKind: type of the sample, as defined by the RTPS Standard. Healthy messages from a topic are always ALIVE.
• WriterGUID: Signature of the sender (Publisher) the message comes from.
• OwnershipStrength: When several senders are writing the same data, this field can be used to determine which data is more reliable.
• SourceTimestamp: A timestamp on the sender side that indicates the moment the sample was encapsulated and sent.

This meta-data can be used to implement filters:

 if((m_info->sampleKind == ALIVE)& (m_info->OwnershipStrength > 25 ){
     //Process data
}

Defining callbacks¶

As we saw in the example, both the Publisher and Subscriber have a set of callbacks you can use in your application. These callbacks are to be implemented within classes that derive from SubscriberListener or PublisherListener. The following table gathers information about the possible callbacks that can be implemented in both cases:

Callback	Publisher	Subscriber
onNewDataMessage	N	Y
onSubscriptionMatched	N	Y
onPublicationMatched	Y	N

Managing the Participant¶

To create a RTPSParticipant, the process is very similar to the one shown in the Publisher-Subscriber layer.

RTPSParticipantAttributes Pparam;
Pparam.setName("participant");
RTPSParticipant* p = RTPSDomain::createRTPSParticipant(PParam);

The RTPSParticipantAttributes structure is equivalent to the rtps member of ParticipantAttributes field in the Publisher-Subscriber Layer, so you can configure your RTPSParticipant the same way as before:

RTPSParticipantAttributes Pparam;
Pparam.setName("my_participant");
//etc.

Managing the Writers and Readers¶

As the RTPS standard specifies, Writers and Readers are always associated with a History element. In the Publisher-Subscriber Layer its creation and management is hidden, but in the Writer-Reader Layer you have full control over its creation and configuration.

Writers are configured with a WriterAttributes structure. They also need a WriterHistory which is configured with a HistoryAttributes structure.

HistoryAttributes hatt;
WriterHistory * history = new WriterHistory(hatt);
WriterAttributes watt;
RTPSWriter* writer = RTPSDomain::createRTPSWriter(rtpsParticipant,watt,hist);

The creation of a Reader is similar. Note that in this case you can provide a ReaderListener instance that implements your callbacks:

class MyReaderListener:public ReaderListener;
MyReaderListener listen;
HistoryAttributes hatt;
ReaderHistory * history = new ReaderHistory(hatt);
ReaderAttributes ratt;
RTPSReader* reader = RTPSDomain::createRTPSReader(rtpsParticipant,watt,hist,&listen);

Using the History to Send and Receive Data¶

In the RTPS Protocol, Readers and Writers save the data about a topic in their associated History. Each piece of data is represented by a Change, which eprosima Fast RTPS implements as CacheChange_t. Changes are always managed by the History. As an user, the procedure for interacting with the History is always the same:

1. Request a CacheChange_t from the History
2. Use it
3. Release it

You can interact with the History of the Writer to send data:

CacheChange_t* ch = writer->newCacheChange(ALIVE); //Request a change from the history
ch->serializedPayload->length = sprintf(ch->serializedPayload->data,"My String %d",2); //Write serialized data into the change
history->add_change(ch); //Insert change back into the history. The Writer takes care of the rest.

If your topic data type has several fields, you will have to provide functions to serialize and deserialize your data in and out of the CacheChange_t. FastRTPSGen does this for you.

You can receive data from within a ReaderListener callback method as we did in the Publisher-Subscriber Layer:

class MyReaderListener: public ReaderListener
{
    public:

    MyReaderListener(){}
    ~MyReaderListener(){}
    void onNewCacheChangeAdded(RTPSReader* reader,const CacheChange_t* const change)
    {
        printf("%s\n",change->serializedPayload.data); // The incoming message is enclosed within the `change` in the function parameters
        reader->getHistory()->remove_change((CacheChange_t*)change); //Once done, remove the change
    }
}

Additionally you can read an incoming message directly by interacting with the History:

reader->waitForUnreadMessage(); //Blocking method
CacheChange_t* change;
if(reader->nextUnreadCache(&change)) //Take the first unread change present in the History
{
    /* use data */
}
history->remove_change(change); //Once done, remove the change

Setting the Input and Output Channels¶

As in the Publisher-Subscriber Layer, you can specify the input and output channels you want your Writer/Reader to listen to or speak from in the form of Locators. This configuration overrides the one inherited from the RTPSParticipant.

WriterAttributes Wattr;
Locator_t my_locator;
//Set up your Locator
Wattr.endpoint.OutLocatorList.push_back(my_locator);

Setting the data durability kind¶

The Durability parameter defines the behaviour of the Writer regarding samples already sent when a new Reader matches. eProsima Fast RTPS offers two Durability options:

• VOLATILE (default): Messages are discarded as they are sent. If a new Reader matches after message n, it will start received from message n+1.
• TRANSIENT_LOCAL: The Writer saves a record of the lask k messages it has sent. If a new reader matches after message n, it will start receiving from message n-k

To choose you preferred option:

WriterAttributes Wparams;
Wparams.endpoint.durabilityKind = TRANSIENT_LOCAL;

Because in the Writer-Reader layer you have control over the History, in TRANSIENT_LOCAL mode the Writer send all changes you have not explicitly released from the History.

Changing the maximum size of the payload¶

You can choose the maximum size of they Payload that can go into a CacheChange_t. Be sure to choose a size that allows it to hold the biggest possible piece of data:

HistoryAttributes.payloadMaxSize  = 250; //Defaults to 500 bytes

Changing the size of the History¶

You can specify a maximum amount of changes for the History to hold and initial amount of allocated changes:

HistoryAttributes.initialReservedCaches = 250; //Defaults to 500
HistoryAttributes.maximumReservedCaches = 500; //Dedaults to 0 = Unlimited Changes

When the initial amount of reserved changes is lower than the maximum, the History will allocate more changes as they are needed until it reaches the maximum size.

Arrays¶

fastrtpsgen supports unidimensional and multidimensional arrays. Arrays are always mapped to std::array containers. The following table shows the array types supported and how they map.

IDL	C++11
char a[5]	std::array<char,5> a
octet a[5]	std::array<uint8_t,5> a
short a[5]	std::array<int16_t,5> a
unsigned short a[5]	std::array<uint16_t,5> a
long long a[5]	std::array<int64_t,5> a
unsigned long long a[5]	std::array<uint64_t,5> a
float a[5]	std::array<float,5> a
double a[5]	std::array<double,5> a

Sequences¶

fastrtpsgen fupports sequences, which map into the STD vector container. The following table represents how the map between IDL and C++11 is handled.

IDL	C++11
sequence<char>	std::vector<char>
sequence<octet>	std::vector<uint8_t>
sequence<short>	std::vector<int16_t>
sequence<unsigned short>	std::vector<uint16_t>
sequence<long long>	std::vector<int64_t>
sequence<unsigned long long>	std::vector<uint64_t>
sequence<float>	std::vector<float>
sequence<double>	std::vector<double>

Structures¶

You can define an IDL structure with a set of members with multiple types. It will be converted into a C++ class with each member mapped as an attributes plus method to get and set each member.

The following IDL structure:

struct Structure
{
octet octet_value;
long long_value;
string string_value;
};

Would be converted to:

class Structure
{
public:
   Structure();
   ~Structure();
   Structure(const Structure &x);
   Structure(Structure &&x);
   Structure& operator=( const Structure &x);
   Structure& operator=(Structure &&x);

   void octet_value(uint8_t _octet_value);
   uint8_t octet_value() const;
   uint8_t& octet_value();
   void long_value(int64_t _long_value);
   int64_t long_value() const;
   int64_t& long_value();
   void string_value(const std::string
      &_string_value);
   void string_value(std::string &&_string_value);
   const std::string& string_value() const;
   std::string& string_value();

private:
   uint8_t m_octet_value;
   int64_t m_long_value;
   std::string m_string_value;
};

Unions¶

In IDL, a union is defined as a sequence of members with their own types and a discriminant that specifies which member is in use. An IDL union type is mapped as a C++ class with access functions to the union members and the discriminant.

The following IDL union:

union Union switch(long)
{
 case 1:
    octet octet_value;
  case 2:
    long long_value;
  case 3:
    string string_value;
};

Would be converted to:

class Union
{
public:
   Union();
   ~Union();
   Union(const Union &x);
   Union(Union &&x);
   Union& operator=(const Union &x);
   Union& operator=(Union &&x);

   void d(int32t __d);
   int32_t _d() const;
   int32_t& _d();

   void octet_value(uint8_t _octet_value);
   uint8_t octet_value() const;
   uint8_t& octet_value();
   void long_value(int64_t _long_value);
   int64_t long_value() const;
   int64_t& long_value();
   void string_value(const std::string
      &_string_value);
   void string_value(std:: string &&_string_value);
   const std::string& string_value() const;
   std::string& string_value();

private:
   int32_t m__d;
   uint8_t m_octet_value;
   int64_t m_long_value;
   std::string m_string_value;
};

Enumerations¶

An enumeration in IDL format is a collection of identifiers that have a numeric value associated. An IDL enumeration type is mapped directly to the corresponding C++11 enumeration definition.

The following IDL enumeration:

enum Enumeration
{
    RED,
    GREEN,
    BLUE
};

Would be converted to:

enum Enumeration : uint32_t
{
    RED,
    GREEN,
    BLUE
};

Keyed Types¶

In order to use keyed topics the user should define some key members inside the structure. This is achieved by writting “@Key” before the members of the structure you want to use as keys. For example in the following IDL file the id and type field would be the keys:

struct MyType
{
    @Key long id;
    @Key string type;
    long positionX;
    long positionY;
};

fastrtpsgen automatically detects these tags and correctly generates the serialization methods for the key generation function in TopicDataType (getKey). This function will obtain the 128 MD5 digest of the big endian serialization of the Key Members.

Version 1.3.0¶

This release introduces several new features:

• Unbound Arrays support: Now you can send variable size data arrays.
• Extended Fragmentation Configuration: It allows you to setup a Message/Fragment max size different to the standard 64Kb limit.
• Improved logging system: Get even more introspection about the status of your communications system.
• Static Discovery: Use XML to map your network and keep discovery traffic to a minimum.
• Stability and performance improvements: A new iteration of our built-in performance tests will make benchmarking easier for you.
• ReadTheDocs Support: We improved our documentation format and now our installation and user manuals are available online on ReadTheDocs.

Version 1.2.0¶

This release introduces two important new features:

• Flow Controllers: A mechanism to control how you use the available bandwidth avoiding data bursts. The controllers allow you to specify the maximum amount of data to be sent in a specific period of time. This is very useful when you are sending large messages requiring fragmentation.
• Discovery Listeners: Now the user can subscribe to the discovery information to know the entities present in the network (Topics, Publishers & Subscribers) dynamically without prior knowledge of the system. This enables the creation of generic tools to inspect your system.

But there is more:

• Full ROS2 Support: Fast RTPS is used by ROS2, the upcoming release of the Robot Operating System (ROS).
• Better documentation: More content and examples.
• Improved performance.
• Bug fixing.