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.hpp
├── HelloWorld.idl
├── HelloWorldCdrAux.hpp
├── HelloWorldCdrAux.ipp
├── HelloWorldPublisher.cxx
├── HelloWorldPublisher.h
├── HelloWorldPubSubMain.cxx
├── HelloWorldPubSubTypes.cxx
├── HelloWorldPubSubTypes.h
├── HelloWorldSubscriber.cxx
├── HelloWorldSubscriber.h
├── HelloWorldTypeObjecSupport.cxx
└── HelloWorldTypeObjecSupport.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/fastdds/
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\fastdds <major>.<minor>.<patch>\include\fastdds
andC:\Program Files\eProsima\fastdds <major>.<minor>.<patch>\include\fastcdr\
for Fast DDS and Fast CDR respectively. The compiled libraries of both can be found in the directoryC:\Program Files\eProsima\fastdds <major>.<minor>.<patch>\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 thePATH
.
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:
Generate C++ definitions for a custom topic.
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
data_writer->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.