3. Building a publish/subscribe application

Fast DDS-Gen can be used to build a fully functional publication/subscription application from an IDL file that defines the Topic under which messages are published and received. The application generated allows for the creation of as many publishers and subscribers as desired, all belonging to the same Domain and communicating using the same Topic.

3.1. Background

eProsima Fast DDS-Gen is a Java application that generates eProsima Fast DDS source code using the data types defined in an IDL (Interface Definition Language) file. This generated source code can be used in any Fast DDS application in order to define the data type of a topic, which will later be used to publish or subscribe. Please refer to Fast DDS-Gen introduction for more information.

3.2. Prerequisites

First of all, follow the steps outlined in the Installation Manual for the installation of eProsima Fast DDS and all its dependencies. Moreover, perform the steps outlined in Linux installation of Fast DDS-Gen or in Window installation of Fast DDS-Gen, depending on the operating system, for the installation of the eProsima Fast DDS-Gen tool.

3.3. Create the application workspace

The application workspace will have the following structure at the end of the project. The file build/HelloWorld is the generated Fast DDS application.

.
└── FastDDSGenHelloWorld
    ├── build
    │   ├── CMakeCache.txt
    │   ├── CMakeFiles
    │   ├── cmake_install.cmake
    │   ├── HelloWorld
    │   ├── libHelloWorld_lib.a
    │   └── Makefile
    ├── CMakeLists.txt
    ├── HelloWorld.cxx
    ├── HelloWorld.h
    ├── HelloWorld.idl
    ├── HelloWorldCdrAux.hpp
    ├── HelloWorldCdrAux.ipp
    ├── HelloWorldPublisher.cxx
    ├── HelloWorldPublisher.h
    ├── HelloWorldPubSubMain.cxx
    ├── HelloWorldPubSubTypes.cxx
    ├── HelloWorldPubSubTypes.h
    ├── HelloWorldSubscriber.cxx
    └── HelloWorldSubscriber.h

Execute the following command to create the directory in which the files generated by Fast DDS-Gen will be saved.

mkdir FastDDSGenHelloWorld && cd FastDDSGenHelloWorld
mkdir build

3.4. Import linked libraries and its dependencies

The DDS application requires the Fast DDS and Fast CDR libraries. The way of making these accessible from the workspace depends on the installation procedure followed in the Installation Manual.

3.4.1. Installation from binaries

If the installation from binaries has been followed, these libraries are already accessible from the workspace.

  • On Linux: The header files can be found in directories /usr/include/fastrtps/ and /usr/include/fastcdr/ for Fast DDS and Fast CDR respectively. The compiled libraries of both can be found in the directory /usr/lib/.

  • On Windows: The header files can be found in directories C:\Program Files\eProsima\fastrtps 2.0.0\include\fastrtps and C:\Program Files\eProsima\fastrtps 2.0.0\include\fastcdr\ for Fast DDS and Fast CDR respectively. The compiled libraries of both can be found in the directory C:\Program Files\eProsima\fastrtps 2.0.0\lib\.

3.4.2. Colcon installation

If the Colcon installation has been followed, there are several ways to import the libraries. To make these accessible only from the current shell session, run one of the following two commands.

  • On Linux:

source <path/to/Fast-DDS/workspace>/install/setup.bash
  • On Windows:

<path/to/Fast-DDS/workspace>/install/setup.bat

However, to make these accessible from any session, add the Fast DDS installation directory to the $PATH variable in the shell configuration files running the following command.

  • On Linux:

echo 'source <path/to/Fast-DDS/workspace>/install/setup.bash' >> ~/.bashrc
  • On Windows: Open the Edit the system environment variables control panel and add <path/to/Fast-DDS/workspace>/install/setup.bat to the PATH.

3.5. Creating the IDL file with the data type

To build a minimal application, the Topic must be defined by means of an IDL file. For this example the Topic data type defined by IDL is just a string message. Topics are explained in more detail in Topic, while the Topic data types to be defined using IDL are presented in Definition of data types. In the preferred text editor, create the HelloWorld.idl file with the following content and save it in the FastDDSGenHelloWorld directory.

// HelloWorld.idl
struct HelloWorld
{
    string message;
};

Then, this file is translated to something Fast DDS understands. For this, use the Fast DDS-Gen code generation tool, which can do two different things:

  1. Generate C++ definitions for a custom topic.

  2. Generate a functional example that uses the topic data.

The second option is the one used to create this publish/subscribe application, while the first option is applied in this other tutorial: Writing a simple C++ publisher and subscriber application.

3.6. Generating a minimal functional example

If the steps outlined in the Installation Manual have been followed, then Fast DDS, Fast CDR, and Fast-RTPS-Gen should be installed in the system.

3.6.1. Generate the Fast DDS source code

The application files are generated using the following command. The -example option creates an example application, and the CMake files needed to build it. In the workspace directory (FastDDSGenHelloWorld directory), execute one of the following commands according to the installation followed and the operating system.

  • On Linux:

    • For an installation from binaries or a colcon installation:

    <path-to-Fast-DDS-workspace>/src/fastddsgen/scripts/fastddsgen -example CMake HelloWorld.idl
    
    • For a stand-alone installation, run:

    <path-to-Fast-DDS-Gen>/scripts/fastddsgen -example CMake HelloWorld.idl
    
  • On Windows:

    • For a colcon installation:

    <path-to-Fast-DDS-workspace>/src/fastddsgen/scripts/fastddsgen.bat -example CMake HelloWorld.idl
    
    • For a stand-alone installation, run:

    <path-to-Fast-DDS-Gen>/scripts/fastddsgen.bat -example CMake HelloWorld.idl
    
    • For an installation from binaries, run:

    fastddsgen.bat -example CMake HelloWorld.idl
    

Warning

The colcon installation does not build the fastddsgen.jar file although it does download the Fast DDS-Gen repository. The following commands must be executed to build the Java executable:

cd <path-to-Fast-DDS-workspace>/src/fastddsgen
gradle assemble

3.6.2. Build the Fast DDS application

Then, compile the generated code executing the following commands from the FastDDSGenHelloWorld directory.

  • On Linux:

cd build
cmake ..
make
  • On Windows:

cd build
cmake -G "Visual Studio 15 2017 Win64" ..
cmake --build .

3.6.3. Run the Fast DDS application

The application build can be used to spawn any number of publishers and subscribers associated with the topic.

  • On Linux:

./HelloWorld publisher
./HelloWorld subscriber
  • On Windows:

HelloWorld.exe publisher
HelloWorld.exe subscriber

Each time <Enter> is pressed on the Publisher, a new datagram is generated, sent over the network and received by Subscribers currently online. If more than one subscriber is available, it can be seen that the message is equally received on all listening nodes.

The values on the custom IDL-generated data type can also be modified as indicated below.

HelloWorld sample; //Auto-generated container class for topic data from Fast DDS-Gen
sample.msg("Hello there!"); // Add contents to the message
publisher->write(&sample); //Publish

Warning

It may be necessary to set up a special rule in the Firewall for eprosima Fast DDS to work correctly on Windows.

3.7. Summary and next steps

In this tutorial, a publisher/subscriber DDS application using Fast DDS-Gen has been built. The tutorial also describes how to generate IDL files that contain the description of the Topic data type.

To continue developing DDS applications please take a look at the eProsima Fast DDS examples on github for ideas on how to improve this basic application through different configuration options, and also for examples of advanced Fast DDS features.