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 Micro to publish and subscribe topics of user defined types, the types have to be defined and programmatically registered with RTI Connext Micro. A registered type is then serialized and deserialized by RTI Connext Micro through a pluggable type interface that each type must implement.

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

IDL Type Definition

rtiddsgen for RTI Connext Micro accepts types defined in IDL. The HelloWorld examples included with RTI Connext 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 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 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 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 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 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 Micro Application

An RTI Connext 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 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 Micro

RTI Connext 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 Micro.

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