5.3.3. STATIC Discovery Settings
Fast DDS allows for the substitution of the SEDP protocol for the EDP phase with a static version that completely eliminates EDP meta traffic. This can become useful when dealing with limited network bandwidth and a well-known schema of DataWriters and DataReaders. If all DataWriters and DataReaders, and their Topics and data types, are known beforehand, the EDP phase can be replaced with a static configuration of peers. It is important to note that by doing this, no EDP discovery meta traffic will be generated, and only those peers defined in the configuration will be able to communicate. The STATIC discovery related settings are:
Name |
Description |
---|---|
It activates the STATIC discovery protocol. |
|
Specifies an XML content with a description of the remote DataWriters and |
|
It defines the behavior of the DomainParticipant initial announcements (PDP phase). |
5.3.3.1. STATIC EDP
To activate the STATIC EDP, the SEDP must be disabled on the WireProtocolConfigQos
.
This can be done either by code or using an XML configuration file:
C++ |
DomainParticipantQos pqos;
pqos.wire_protocol().builtin.discovery_config.use_SIMPLE_EndpointDiscoveryProtocol = false;
pqos.wire_protocol().builtin.discovery_config.use_STATIC_EndpointDiscoveryProtocol = true;
|
XML |
<participant profile_name="participant_profile_static_edp">
<rtps>
<builtin>
<discovery_config>
<EDP>STATIC</EDP>
</discovery_config>
</builtin>
</rtps>
</participant>
|
Currently two different formats of exchanging information in the Participant Discovery Phase (PDP) are supported: the default one and another that reduces the network bandwidth used. Static Discovery’s Exchange Format explains how to change this.
5.3.3.2. STATIC EDP XML Configuration Specification
Since activating STATIC EDP suppresses all EDP meta traffic, the information about the remote entities (DataWriters and DataReaders) must be statically specified, which is done using dedicated XML files. A DomainParticipant may load several of such configuration files so that the information about different entities can be contained in one file, or split into different files to keep it more organized. Fast DDS provides a Static Discovery example that implements this EDP discovery protocol.
The following table describes all the possible elements of a STATIC EDP XML configuration file. A full example of such file can be found in STATIC EDP XML Example.
Name |
Description |
Values |
Default |
---|---|---|---|
|
Mandatory. |
|
0 |
|
EntityId of the DataReader/DataWriter. |
|
0 |
|
It indicates if QOS is expected inline |
|
|
|
Mandatory. |
|
|
|
Mandatory. |
|
|
|
The kind of topic. |
|
|
|
The name of a partition of the remote peer. |
|
|
|
Unicast locator of the DomainParticipant. |
||
|
Multicast locator of the DomainParticipant. |
||
|
See the ReliabilityQosPolicy section. |
||
|
See the DurabilityQosPolicy section. |
|
|
|
See Ownership QoS. |
||
|
Defines the liveliness of the remote peer. |
||
|
5.3.3.2.1. Locators definition
Locators for remote peers are configured using <unicastLocator>
and <multicastLocator>
tags.
These take no value, and the locators are defined using tag elements.
Locators defined with <unicastLocator>
and <multicastLocator>
are accumulative, so they can be repeated to
assign several remote endpoints locators to the same peer.
address
: a mandatorystring
representing the locator address.port
: an optionaluint16_t
representing a port on that address.
5.3.3.2.2. Ownership QoS
The ownership of the topic can be configured using <ownershipQos>
tag.
It takes no value, and the configuration is done using tag elements:
kind
: can be one ofSHARED_OWNERSHIP_QOS
orEXCLUSIVE_OWNERSHIP_QOS
. This element is mandatory withing the tag.strength
: an optionaluint32_t
specifying how strongly the remote DomainParticipant owns the Topic. This QoS can be set on DataWriters only. If not specified, default value is zero.
5.3.3.2.3. Liveliness QoS
The LivelinessQosPolicy of the remote peer is configured using <livelinessQos>
tag.
It takes no value, and the configuration is done using tag elements:
kind
: can be any ofAUTOMATIC_LIVELINESS_QOS
,MANUAL_BY_PARTICIPANT_LIVELINESS_QOS
orMANUAL_BY_TOPIC_LIVELINESS_QOS
. This element is mandatory withing the tag.leaseDuration_ms
: an optionaluint32
specifying the lease duration for the remote peer. The special valueINF
can be used to indicate infinite lease duration. If not specified, default value isINF
5.3.3.3. Checking STATIC EDP XML Files
Before loading a static EDP XML file, it would be useful to check its validity and make sure the file will be
successfully loaded.
This verification can be performed on DomainParticipantFactory using
DomainParticipantFactory::check_xml_static_discovery()
, using either XML files or the configuration directly,
as in the examples below.
// The (file://) flag is optional.
std::string file = "file://static_Discovery.xml";
DomainParticipantFactory* factory = DomainParticipantFactory::get_instance();
if (RETCODE_OK != factory->check_xml_static_discovery(file))
{
std::cout << "Error parsing xml file " << file << std::endl;
}
// The (data://) flag is required to load the configuration directly.
std::string fileData = "data://<?xml version=\"1.0\" encoding=\"utf-8\"?>" \
"<staticdiscovery>" \
"<participant>" \
"<name>HelloWorldPublisher</name>" \
"<writer>" \
"<userId>1</userId>" \
"<entityID>2</entityID>" \
"<topicName>HelloWorldTopic</topicName>" \
"<topicDataType>HelloWorld</topicDataType>" \
"</writer>" \
"</participant>" \
"</staticdiscovery>";
if (RETCODE_OK != factory->check_xml_static_discovery(fileData))
{
std::cout << "Error parsing xml file data:" << std::endl << fileData << std::endl;
}
5.3.3.3.1. STATIC EDP XML Example
The following is a complete example of a configuration XML file for two remote DomainParticipant, a DataWriter and a DataReader. This configuration must agree with the configuration used to create the remote DataReader/DataWriter. Otherwise, communication between DataReaders and DataWriters may be affected. If any non-mandatory element is missing, it will take the default value. As a rule of thumb, all the elements that were specified on the remote DataReader/DataWriter creation should be configured.
XML |
<staticdiscovery>
<participant>
<name>HelloWorldSubscriber</name>
<reader>
<userId>3</userId>
<entityID>4</entityID>
<expects_inline_qos>true</expects_inline_qos>
<topicName>HelloWorldTopic</topicName>
<topicDataType>HelloWorld</topicDataType>
<topicKind>WITH_KEY</topicKind>
<partitionQos>HelloPartition</partitionQos>
<partitionQos>WorldPartition</partitionQos>
<unicastLocator address="192.168.0.128" port="5000"/>
<unicastLocator address="10.47.8.30" port="6000"/>
<multicastLocator address="239.255.1.1" port="7000"/>
<reliabilityQos>BEST_EFFORT_RELIABILITY_QOS</reliabilityQos>
<durabilityQos>VOLATILE_DURABILITY_QOS</durabilityQos>
<ownershipQos kind="SHARED_OWNERSHIP_QOS"/>
<livelinessQos kind="AUTOMATIC_LIVELINESS_QOS" leaseDuration_ms="1000"/>
<disablePositiveAcks>
<enabled>true</enabled>
</disablePositiveAcks>
</reader>
</participant>
<participant>
<name>HelloWorldPublisher</name>
<writer>
<unicastLocator address="192.168.0.120" port="9000"/>
<unicastLocator address="10.47.8.31" port="8000"/>
<multicastLocator address="239.255.1.1" port="7000"/>
<userId>5</userId>
<entityID>6</entityID>
<topicName>HelloWorldTopic</topicName>
<topicDataType>HelloWorld</topicDataType>
<topicKind>WITH_KEY</topicKind>
<partitionQos>HelloPartition</partitionQos>
<partitionQos>WorldPartition</partitionQos>
<reliabilityQos>BEST_EFFORT_RELIABILITY_QOS</reliabilityQos>
<durabilityQos>VOLATILE_DURABILITY_QOS</durabilityQos>
<ownershipQos kind="SHARED_OWNERSHIP_QOS" strength="50"/>
<livelinessQos kind="AUTOMATIC_LIVELINESS_QOS" leaseDuration_ms="1000"/>
<disablePositiveAcks>
<enabled>true</enabled>
<duration>
<sec>300</sec>
</duration>
</disablePositiveAcks>
</writer>
</participant>
</staticdiscovery>
|
5.3.3.4. Loading STATIC EDP XML Files
Statically discovered remote DataReaders/DataWriters must define a unique userID on their profile, whose value must agree with the one specified in the discovery configuration XML. This is done by setting the user ID on the DataReaderQos/DataWriterQos:
C++ |
// Configure the DataWriter
DataWriterQos wqos;
wqos.endpoint().user_defined_id = 1;
// Configure the DataReader
DataReaderQos rqos;
rqos.endpoint().user_defined_id = 3;
|
XML |
<data_writer profile_name="writer_xml_conf_static_discovery">
<userDefinedID>3</userDefinedID>
</data_writer>
<data_reader profile_name="reader_xml_conf_static_discovery">
<userDefinedID>5</userDefinedID>
</data_reader>
|
On the local DomainParticipant, you can load STATIC EDP configuration content specifying the file containing it.
C++ |
DomainParticipantQos pqos;
pqos.wire_protocol().builtin.discovery_config.static_edp_xml_config("file://RemotePublisher.xml");
pqos.wire_protocol().builtin.discovery_config.static_edp_xml_config("file://RemoteSubscriber.xml");
|
XML |
<participant profile_name="participant_profile_static_load_xml">
<rtps>
<builtin>
<discovery_config>
<static_edp_xml_config>file://RemotePublisher.xml</static_edp_xml_config>
<static_edp_xml_config>file://RemoteSubscriber.xml</static_edp_xml_config>
</discovery_config>
</builtin>
</rtps>
</participant>
|
Or you can specify the STATIC EDP configuration content directly.
C++ |
DomainParticipantQos pqos;
pqos.wire_protocol().builtin.discovery_config.static_edp_xml_config(
"data://<?xml version=\"1.0\" encoding=\"utf-8\"?>" \
"<staticdiscovery><participant><name>RTPSParticipant</name></participant></staticdiscovery>");
|