Generating Type Support with rtiddsgen

Objectives of this user guide:

• Using rtiddsgen to generate user type support code in C or C++

Why Use rtiddsgen?

For RTI Connext DDS Micro to publish and subscribe topics of user defined types, the types have to be defined and programmatically registered with RTI Connext DDS Micro. A registered type is then serialized and deserialized by RTI Connext DDS Micro through a pluggable type interface that each type must implement.

Rather than have users manually implement each new type, RTI Connext DDS Micro provides the rtiddsgen utility for automatically generating type support code.

IDL Type Definition

rtiddsgen for RTI Connext DDS Micro accepts types defined in IDL. The HelloWorld examples included with RTI Connext DDS Micro use the following HelloWorld.idl:

        struct HelloWorld {
            string<128> msg;
        };

For further reference, see RTI Documentation, the "Core Libraries and Utilities User's Manual" for RTI Connext DDS, section 3.3 (Creating User Data Types with IDL).

Generating Type Support

Before running rtiddsgen, some environment variables must be set:

• RTIMEHOME sets the path of the RTI Connext DDS Micro installation directory
• RTIMEARCH sets the platform architecture (e.g. i86Linux2.6gcc4.4.5 or i86Win32VS2010)
• JREHOME sets the path for a Java JRE

Note that a JRE is shipped with RTI Connext DDS Micro on platforms supported for the execution of rtiddsgen (Linux, Windows, and Mac OS X). It is not necessary to set JREHOME on these platforms, unless a specific JRE is preferred.

C

Run rtiddsgen from the command line to generate C language type support for a UserType.idl (and replace any existing generated files):

    > cd $rti_connext_micro_root/rtiddsgen/scripts
    > rtiddsgen -micro -language C -replace UserType.idl

C++

Run rtiddsgen from the command line to generate C++ language type support for a UserType.idl (and replace any existing generated files):

    > cd $rti_connext_micro_root/rtiddsgen/scripts
    > rtiddsgen -micro -language C++ -replace UserType.idl

on command-line options

In order to taget RTI Connext DDS Micro when generating code with rtiddsgen, the -micro option must be specified on the command line.

It is possible to list all command-line options specifically supported by rtiddsgen for RTI Connext DDS Micro, by doing:

    > cd $rti_connext_micro_root/rtiddsgen/scripts
    > rtiddsgen -micro -help

Existing users might notice that that previously available options, "-language microC" and "-language microC++", have now been replaced by "-micro -language C" and "-micro -language C++" respectively. It is still possible to specify "microC" and "microC++" for backwards compatibility, but users are advised to switch to using the "-micro" command-line option along with other arguments.

Generated Type Support Files

rtiddsgen will produce the following header and source files for each IDL file passed to it:

• UserType.h and UserType.c(xx) implement creation/intialization and deletion of a single sample and a sequence of samples of the type (or types) defined in the IDL description.

• UserTypePlugin.h and UserTypePlugin.c(xx) implement the pluggable type interface that RTI Connext DDS Micro uses to serialize and deserialize the type.

• UserTypeSupport.h and UserTypeSupport.c(xx) define type-specific DataWriters and DataReaders for user-defined types.

Using custom data-types in an RTI Connext DDS Micro Application

An RTI Connext DDS Micro application must first of all include the generated headers. Then, it must register the type with the DomainParticipant before a topic of that type can be defined. For an example HelloWorld type, the following code registers the type with the participant and then creates a topic of that type:

       #include "HelloWorldPlugin.h"
       
       /* ... */
   
       retcode = DDS_DomainParticipant_register_type(application->participant,
                                                     "HelloWorld",
                                                     HelloWorldTypePlugin_get());
       if (retcode != DDS_RETCODE_OK)
       {
           /* Log an error */
           goto done;
       }

       application->topic =
           DDS_DomainParticipant_create_topic(application->participant,
                                              "Example HelloWorld",
                                              "HelloWorld",
                                              &DDS_TOPIC_QOS_DEFAULT, NULL,
                                              DDS_STATUS_MASK_NONE);

       if (application->topic == NULL)
       {
           /* Log an error */
           goto done;
       }

See the full HelloWorld examples for further reference.

Customizing generated code

rtiddsgen now enables RTI Connext DDS Micro users to select whether they want to generate code to subscribe and/or publish a custom data-type. When generating code for subscription, only those parts of code dealing with deserialization of data and the implementation of a typed DataReader endpoint are generated. Conversevely, only those parts of code addressing serialization and the implementation of a DataWriter are considered when generating publishing code.

Control over these option is provide by two command-line arguments:

• -reader : generates code for deserializing custom data-types and creating DataReaders from them.
• -writer : generates code for serialiazing custom data-types and creating DataWriters from them.

If none of these two options is supplied to rtiddsgen, they will be both considered active, and code for both DataReaders and DataWriters will be generated. If any of the two is specified than only those passed as command line are enabled.

Unsupported Features of rtiddsgen with RTI Connext DDS Micro

RTI Connext DDS Micro supports a subset of the features and options in rtiddsgen. Use rtiddsgen -micro -help to see the list of features supported by rtiddsgen for RTI Connext DDS Micro.

Of note, generation of example publisher/subscriber code and makefiles to compile generated files is not yet available when targeting RTI Connext DDS Micro.