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
STATIC EDP	It activates the STATIC discovery protocol.
STATIC EDP XML Configuration Specification	Specifies an XML content with a description of the remote DataWriters and DataReaders.
Initial Announcements	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
`<userId>`	Mandatory. Uniquely identifies the DataReader/DataWriter.	`uint16_t`	0
`<entityID>`	EntityId of the DataReader/DataWriter.	`uint16_t`	0
`<expectsInlineQos>`	It indicates if QOS is expected inline (DataReader only).	`bool`	`false`
`<topicName>`	Mandatory. The topic of the remote DataReader/DataWriter. Should match with one of the topics of the local DataReaders/DataWriters.	`string_255`
`<topicDataType>`	Mandatory. The data type of the topic.	`string_255`
`<topicKind>`	The kind of topic.	`NO_KEY` `WITH_KEY`	`NO_KEY`
`<partitionQos>`	The name of a partition of the remote peer. Repeat to configure several partitions.	`string`
`<unicastLocator>`	Unicast locator of the DomainParticipant. See Locators definition.
`<multicastLocator>`	Multicast locator of the DomainParticipant. See Locators definition.
`<reliabilityQos>`	See the ReliabilityQosPolicy section.	`BEST_EFFORT_RELIABILITY_QOS` `RELIABLE_RELIABILITY_QOS`	`BEST_EFFORT_RELIABILITY_QOS`
`<durabilityQos>`	See the DurabilityQosPolicy section.	`VOLATILE_DURABILITY_QOS` `TRANSIENT_LOCAL_DURABILITY_QOS` `TRANSIENT_DURABILITY_QOS`	`VOLATILE_DURABILITY_QOS`
`<ownershipQos>`	See Ownership QoS.
`<livelinessQos>`	Defines the liveliness of the remote peer. See Liveliness QoS.
`<disablePositiveAcks>`	See DisablePositiveACKsQosPolicy.	See DisablePositiveAcks

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 mandatory string representing the locator address.
port: an optional uint16_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 of SHARED_OWNERSHIP_QOS or EXCLUSIVE_OWNERSHIP_QOS. This element is mandatory withing the tag.
strength: an optional uint32_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 of AUTOMATIC_LIVELINESS_QOS, MANUAL_BY_PARTICIPANT_LIVELINESS_QOS or MANUAL_BY_TOPIC_LIVELINESS_QOS. This element is mandatory withing the tag.
leaseDuration_ms: an optional uint32 specifying the lease duration for the remote peer. The special value INF can be used to indicate infinite lease duration. If not specified, default value is INF

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 (ReturnCode_t::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 (ReturnCode_t::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>
            <expectsInlineQos>true</expectsInlineQos>
            <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>");