eProsima Discovery Server

The RTPS standard specifies in section 8.5 a non-centralized, distributed, simple discovery mechanism. This mechanism was devised to allow interoperability between independent vendor-specific implementations but it is not expected to be optimal in every environment.

Commercial support

Looking for commercial support? Write us to [email protected]

Find more about us at eProsima’s webpage.

Overview

There are several scenarios where the simple discovery mechanism is unsuitable, or it just simply cannot be applied:

• A high number of endpoint entities are continuously entering and exiting a large network.
• Networks without multicasting capabilities.
• WiFi-based communication networks.

In order to cope with the aforementioned issues, the eProsima Fast DDS discovery mechanisms are extended with a new Discovery Server discovery paradigm. This is based on a client-server architecture, i.e. the metatraffic (message exchange among DDS DomainParticipants to identify each other) is managed by one or several server DomainParticipants (right figure), as opposed to simple discovery (left figure), where metatraffic is exchanged using a message broadcast mechanism like an IP multicast protocol. Please, refer to Fast DDS documentation for further information about the Discovery Server discovery mechanism.

The Discovery Server tool is developed to ease Discovery Server discovery mechanism setup and testing. The Discovery Server tool documentation can be found here.

• Supported platforms
• Installation Guide
• Usage
• Example application
• Testing
• Documentation
• Getting Help

Supported platforms

• Linux
• Windows

Installation Guide

In order to use the Discovery Server tool, it is necessary to have a compatible version of eProsima Fast DDS installed (over release 3.0.0). Fast DDS dependencies as tinyxml must be accessible, either because Fast DDS was build-installed defining THIRDPARTY=ON|FORCE or because those libraries have been specifically installed. The well known cross-platform tool colcon was chosen to simplify the installation of the several mutually dependent CMake projects. In order to use colcon, Python3 and CMake must be first installed. Detailed instructions on how to install the required dependencies can be found in the Discovery Server documentation.

To execute the tests that verify the proper operation of the Discovery Server discovery mechanism, it is necessary to install some Python3 modules. These can be installed using pip.

pip3 install jsondiff==1.2.0 xmltodict==0.12.0 pandas==1.1.2

A discovery-server.repos file is available in order to profit from vcstool capabilities to download the needed repositories.

Linux

1. Create a Discovery Server workspace and download the repos file that will be used to install the Discovery Server tool and its dependencies:

   $ mkdir -p discovery-server-ws/src && cd discovery-server-ws
   $ wget https://raw.githubusercontent.com/eProsima/Discovery-Server/master/discovery-server.repos
   $ vcs import src < discovery-server.repos

2. Finally, use colcon to compile all software. Choose the build configuration by declaring CMAKE_BUILD_TYPE as Debug or Release. For this example, the Debug option has been chosen, which would be the choice of advanced users for debugging purposes.

   $ colcon build --base-paths src
           \ --packages-up-to discovery-server
           \ --cmake-args -DTHIRDPARTY=ON -DLOG_LEVEL_INFO=ON -DCOMPILE_EXAMPLES=ON -DINTERNALDEBUG=ON -DCMAKE_BUILD_TYPE=Debug

3. If you installed the Discovery Server tool following the steps outlined above, you can try the HelloWorldExampleDS. To run the example navigate to the following directory

   <path/to/discovery-server-ws>/discovery-server-ws/install/discovery-server/examples/HelloWorldExampleDS

   and run

   $ ./HelloWorldExampleDS-d --help

   to display the example usage instructions.

   In order to test the HelloWorldExampleDS open three terminals and run the above command. Then run the following command in each terminal:

   • Terminal 1:

     $ cd <path/to/discovery-server-ws>/discovery-server-ws/install/discovery-server/examples/HelloWorldExampleDS
     $ ./HelloWorldExampleDS publisher

   • Terminal 2:

     $ cd <path/to/discovery-server-ws>/discovery-server-ws/install/discovery-server/examples/HelloWorldExampleDS
     $ ./HelloWorldExampleDS subscriber

   • Terminal 3:

     $ cd <path/to/discovery-server-ws>/discovery-server-ws/install/discovery-server/examples/HelloWorldExampleDS
     $ ./HelloWorldExampleDS server

Windows

1. Create a Discovery Server workspace and download the repos file that will be used to install the Discovery Server tool and its dependencies:

   > mkdir discovery-server-ws
   > cd discovery-server-ws
   > mkdir src
   > wget https://raw.githubusercontent.com/eProsima/Discovery-Server/master/discovery-server.repos
   > vcs import src < discovery-server.repos

2. If the generator (compiler) of choice is Visual Studio, launch colcon from a visual studio console. Any console can be setup into a visual studio one by executing a batch file. For example, in VS2017 is usually C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\Tools\VsDevCmd.bat

3. Finally, use colcon to compile all software. Choose the build configuration by declaring CMAKE_BUILD_TYPE as Debug or Release. For this example, the Debug option has been chosen, which would be the choice of advanced users for debugging purposes. If using a multi-configuration generator like Visual Studio we recommend to build both in debug and release modes

   > colcon build --base-paths src
           \ --packages-up-to discovery-server
           \ --cmake-args -DTHIRDPARTY=ON -DLOG_LEVEL_INFO=ON -DCOMPILE_EXAMPLES=ON -DINTERNALDEBUG=ON -DCMAKE_BUILD_TYPE=Debug
   > colcon build --base-paths src
           \ --packages-up-to discovery-server
           \ --cmake-args -DTHIRDPARTY=ON -DCOMPILE_EXAMPLES=ON -DCMAKE_BUILD_TYPE=Release

4. If you installed the Discovery Server tool following the steps outlined above, you can try the HelloWorldExampleDS. To run the example navigate to the following directory

   <path/to/discovery-server-ws>/discovery-server-ws/install/discovery-server/examples/HelloWorldExampleDS

   and run

   > HelloWorldExampleDS --help

   to display the example usage instructions.

   In order to test the HelloWorldExampleDS open three terminals and run the above command. Then run the following command in each terminal:

   • Terminal 1:

     > cd <path/to/discovery-server-ws>/discovery-server-ws/install/discovery-server/examples/HelloWorldExampleDS
     > HelloWorldExampleDS publisher

   • Terminal 2:

     > cd <path/to/discovery-server-ws>/discovery-server-ws/install/discovery-server/examples/HelloWorldExampleDS
     > HelloWorldExampleDS subscriber

   • Terminal 3:

     > cd <path/to/discovery-server-ws>/discovery-server-ws/install/discovery-server/examples/HelloWorldExampleDS
     > HelloWorldExampleDS server
     

---

NOTE

In order to avoid using vcstool, the following repositories should be downloaded from github into the discovery-server-ws/src directory:

PACKAGE	URL	BRANCH
fastcdr:	https://github.com/eProsima/Fast-CDR.git	master
fastdds:	https://github.com/eProsima/Fast-DDS.git	master
discovery_server:	https://github.com/eProsima/Discovery-Server.git	master
foonathan_memory_vendor:	https://github.com/eProsima/foonathan_memory_vendor.git	master
leethomason/tinyxml2:	https://github.com/leethomason/tinyxml2.git	master

---

Usage

XML profiles

Each setting in Fast DDS can be configured through XML profiles. XML profiles allows to avoid tiresome hard-coded settings within applications sources using XML configuration files. The Fast DDS XML schema was duly updated to accommodate the new Discovery Server tool settings.

• The participant profile <builtin> tag contains a <discovery_config> tag where all discovery-related info is gathered. This new tag contains the following new XML child elements:
  • <discoveryProtocol>: specifies the discovery type through the DiscoveryProtocol enumeration.
  • <discoveryServersList>: specifies the server or servers to which a Client/Server connects.
  • <clientAnnouncementPeriod>: specifies the time span between PDP metatraffic exchange.

An example of XML profiles for a client and a server is shown below.

<participant profile_name="UDP_client" >
  <rtps>
	<builtin>
		<discovery_config>
		  <discoveryProtocol>CLIENT</discoveryProtocol>
		  <discoveryServersList>
			<RemoteServer prefix="4d.49.47.55.45.4c.5f.42.41.52.52.4f">
			  <metatrafficUnicastLocatorList>
				<locator>
				  <udpv4>
					<address>192.168.1.113</address>
					<port>64863</port>
				  </udpv4>
				</locator>
			  </metatrafficUnicastLocatorList>
			</RemoteServer>
		  </discoveryServersList>
		</discovery_config>
	</builtin>
  </rtps>
</participant>

<participant profile_name="UDP_server">
  <rtps>
	<prefix>4d.49.47.55.45.4c.5f.42.41.52.52.4f</prefix>
	<builtin>
		<discovery_config>
		  <discoveryProtocol>SERVER</discoveryProtocol>
		</discovery_config>
		<metatrafficUnicastLocatorList>
			<locator>
				<udpv4>
					<address>192.168.1.113</address>
					<port>64863</port>
				</udpv4>
			</locator>
		</metatrafficUnicastLocatorList>
	</builtin>
  </rtps>
</participant>

Discovery Server executable

The discovery server binary (named after the pattern discovery-server-X.X.X(d) where X.X.X is the version number and the optional d denotes a debug build) is set up from one XML profiles files passed as command-line arguments. To have the tool accessible in the terminal session it is necessary to source the setup file.

• Linux

  $ source <path/to/discovery-server-ws>/discovery-server-ws/install/setup.bash
  $ discovery-server-X.X.X(d) -c config_file.xml

• Windows

  > . <path/to/discovery-server-ws>/discovery-server-ws/install/setup.bat
  > discovery-server-X.X.X(d).exe config_file.xml

Documentation

You can access the documentation online, which is hosted on Read the Docs.