Wanna exchange?

The main purpose to OpenDDS (and DDS, of course) is to exchange data over a network. But what are data?

In DDS, data that can be exchanged are structs. For example we can create a struct containing specific fields, like this one:

struct MyData {
  long counter;
  string message;
  double threshold;
};

This struct describes a piece of data that can be sent and received through DDS. In other words, a topic.

We have to consider that OpenDDS is capable to exchange data between processes created with different languages. For example a C++ publisher can send a topic and it can be received by a Java process. For this reason we have to define the struct that exchange data in both C++ and Java. In order to avoid this (and other) problems, topics are defined in a separate file, using the .idl file format. When we have finished to create it, from this file is possible to create all necessary source files in both Java and C++. We define topics in an agnostic format, and then using some OpenDDS tool we create the C++ or Java files that we need. With this we can create topics only once, avoiding errors because data are defined only once, in one place. In other words, when we decide to create some topic to be exchanged we need to:

1. Define the fields of topics;
2. Define topics in the .idl file;
3. Compile the .idl file for generating C++ files;
4. Compile the .idl file for generating Java files.

Of course if we use only one language, we don't need to create files for the other language. At the moment, we'll focus on C++ rather than Java.

IDL

We need to define the structures that we want to exchange in the IDL. This is a file, written in a C++ style, that defines the structured.

The IDL (Interface Description Language) is a text file that defines structures in a C++ style (but it's not the same syntax). This file contains structures of data that must be exchanged. A structure is defined by the struct keyword. This is an example of structure that contains a real value and a string:

struct SomeUsefulStruct {
  double myPreciousDouble;
  string veryVeryImportantString;
};

As we can see it's not difficult to create a string. In the following table we'll show all the datatypes that can be used inside a string:

As an example, we can try to create a IDL message for checking data. Create a test.idl file, and copy following content:

module Sample {
struct DataTypesList {
  boolean            booleanValue;
  char               charValue;
  wchar              wcharValue;
  string             stringValue;
  wstring            wstringValue;
  octet              octedValue;
  short              shortValue;
  unsigned short     unsignedShortValue;
  long               longValue;
  unsigned long      unsignedLongValue;
  long long          longLongValue;
  unsigned long long unsignedLongLongValue;
  float              floatValue;
  double             doubleValue;
  fixed              fixedValue;
};
 
}; // module Sample

We can save the file, and then build it with the IDL commands:

opendds_idl.exe .\file.idl -o .
tao_idl.exe -Sg file.idl
tao_idl.exe -Sg fileTypeSupport.idl -o .

The compilation is ok and we have a bunch of files. If we open fileC.h we can find the structure converted in C++:

struct  DataTypesList
{
    // TAO_IDL - Generated from
    // be\be_type.cpp:307
    typedef DataTypesList_var _var_type;
    typedef DataTypesList_out _out_type;
    static void _tao_any_destructor (void *);
    ::CORBA::Boolean booleanValue;
    ::CORBA::Char charValue;
    ::CORBA::WChar wcharValue;
    ::TAO::String_Manager stringValue;
    ::TAO::WString_Manager wstringValue;
    ::CORBA::Octet octedValue;
    ::CORBA::Short shortValue;
    ::CORBA::UShort unsignedShortValue;
    ::CORBA::Long longValue;
    ::CORBA::ULong unsignedLongValue;
    ::CORBA::LongLong longLongValue;
    ::CORBA::ULongLong unsignedLongLongValue;
    ::CORBA::Float floatValue;
    ::CORBA::Double doubleValue;
  };

As we can see, the IDL compiler converts IDL datatypes in custom C++ types, that allows to perform some sort of abstraction. They are mapped in C++ in usual data types.

Example

 Let's see an example. We want to build a scenario simulator. The simulator is composed by two processes:

• Gui: this is the simulator map, in which the user can interact with the scenario, with its players and so on;
• Core: This is the simulation core, the part that perform calculus and that have the program logic.

These are two separate processes and they need to talk each other.

We need to create an IDL containing the message that they want to exchange. The type of messages depends on the actions that we want to perform.

A use case is that the user can add and remove players from the scenario. For this use case, the Gui must be able to send a command for adding a player, and a command for removing a player. Also, once that the player is created, the Gui must read position of the player in order to display it in the right position. On the other hand, the Core must receive commands for adding/removing player, sends a reply to the Gui with the result of the operation (yes, it's an handshaking), and then send periodically the position of the player.

We can see this use case in a sequence diagram:

From the use case we can see that we need following messages:

• AddPlayer: This is the message that contains data regarding the player that must be created, like its name, the profile (if it's a F15, a soldier and so on), and its initial position;
• PlayerAdded: This is the reply that contains data regarding a player that's added to the scenario. It contains all previous data and another field, called result, that says if the player was added successfully or not;
• RemovePlayer: This is the message that contains informations about a player that must be removed. We need to specify the player name in it (we suppose that in a scenario a player name is unique);
• PlayerRemoved: This is the message that contains the result of the remove player operation: it contains the data of the removed player, and also a flag that says if the operation was a success or not;
• PlayerPosition: This message contains the position of a player. It contains the name of the player and its position.

So, we need to create an IDL that contains these messages:

#ifndef SIMULATION_IDL_
#define SIMULATION_IDL_
 
module Message {
 
#pragma DCPS_DATA_TYPE "Message::LLA"
 
struct LLA {
  double latitude;
  double longitude;
  double altitude;
};
 
#pragma DCPS_DATA_TYPE "Message::Orientation"
 
struct Orientation {
  double roll;
  double pitch;
  double yaw;
};
 
#pragma DCPS_DATA_TYPE "Message::PlayerPosition"
 
/**
 * Position of a player that is present inside a scenario.
 */
struct PlayerPosition {
  string      name;
  LLA         pos;
  Orientation ori;
};
 
#pragma DCPS_DATA_TYPE "Message::AddPlayer"
 
/**
 * Command for adding a player to the scenario.
 */
struct AddPlayer {
  string      name;
  string      profile;
  LLA         pos;
  Orientation ori;
};
 
#pragma DCPS_DATA_TYPE "Message::RemovePlayer"
 
/**
 * Command for removing a player from the scenario.
 */
struct RemovePlayer {
  string name;
};
 
#pragma DCPS_DATA_TYPE "Message::PlayerAdded"
 
/**
 * Response that says if a player is added to the scenario.
 */
struct PlayerAdded {
  string      name;
  string      profile;
  LLA         pos;
  Orientation ori;
  boolean     result;
};
 
#pragma DCPS_DATA_TYPE "Message::PlayerRemoved"
 
/**
 * Response that says if a player is removed from the scenario.
 */
struct PlayerRemoved {
  string  name;
  boolean result;
};
 
}; // module Message
 
#endif // !SIMULATION_IDL_

This code shows some basic structure, some compositions (for example in PlayerPosition).

At this point we can build the IDL in order to obtain all needed C++ files, so we save our idl in a file, like sample.idl, and give following commands:

opendds_idl.exe sample.idl -o .
tao_idl.exe -Sg sample.idl -o .
tao_idl.exe -Sg sampleTypeSupport.idl -o .

 This creates a bungh of files, that can be included in our project. Let's see in a little more detail the files that we just created with these commands:

•  sampleC.h/sampleC.cpp: These are the files that define the struct that we created, in C++. Every struct contains all member that we defined in the idl file. They contain also some typedef used in the subscribers and in the publishers, and also some overloaded stream operators;
• sampleC.inl: It does not contain anything at the moment, only a comment;
• sampleS.h/sampleS.cpp: These files contain some traits needed by publishers and suscribers. They are used in topic registrations;
• sampleTypeSupportC.h/sampleTypeSupportC.cpp/sampleTypeSupportC.inc/sampleTypeSupportC.inl: in this case these files contains only some OpenDDS headers that can be used when we need to implement topics in our code;
• sampleTypeSupportImpl.h/sampleTypeSupportImpl.cpp: These files define the stream operators for the serialization of structures when they need to be sent/received over the network;
• sampleTypeSupportS.h/sampleTypeSupportS.cpp: These files contains headers needed for the compilation of structures inside our code. Nothing particular.

As you can see, there are a lot of files, but we don't need to know every detail, because we'll see how use them in an high level.

We can also notice another thing: in the .idl file we created our messages into a module; in particular in the Message module. This is translated in our C++ files into a namespace. So we created our structures in IDL in a Message module, and in C++ files these structures are into a Message namespace. This is useful expecially when we want to organize a big number of topics and we want to avoid name collisions with other classes in our code.

How can I use them?

These files are the C++ translation of the IDL description file. In order to use them we need to include these files in our projects, and them use them with the OpenDDS API in order to send and receive data. We'll see in next article how to send them through the network.

Conclusions

In this article we've seen how to create a basic IDL, and we briefly analysed the source code that we created with its compilation. Now we're ready to use them inside our code. In next articles we'll use this code, so stay tuned!

Comments   

0 #4 paintball 2017-09-17 14:49

Hi this is kind of of off topic but I was wondering if blogs
use WYSIWYG editors or if you have to manually code with HTML.

I'm starting a blog soon but have no coding experience so I wanted to get guidance from someone with experience.
Any help would be greatly appreciated!

Quote

0 #3 Marco 2017-07-27 12:52

Quoting Daniele Lupo:

Quoting Marco:

Is there a possibility to define in IDL a byte array?

You can easily create an array of char or octet.

I've seen and tried that array is deprecated but sequence does its job

Quote

0 #2 Daniele Lupo 2017-07-20 23:24

Quoting Marco:

Is there a possibility to define in IDL a byte array?

You can easily create an array of char or octet.

Quote

0 #1 Marco 2017-07-12 16:23

Is there a possibility to define in IDL a byte array?

Quote

Refresh comments list
RSS feed for comments to this post

Add comment