1. About Protocol Buffers Extension

RTI® Connext® Protocol Buffers Extension enables using Protocol Buffers™ data types in Connext applications.

1.1. Use Cases

1.1.1. Protocol buffers definition language support

Protocol Buffers Extension enables developers to use the Protocol Buffers (protobuf) message definition language to define the data types used by Connext applications. The toolchain automatically maps protobuf types to corresponding DDS-XTYPES types, which serve as the foundation for communication over DDS.

1.1.2. DDS-XTYPES type generation

Protocol Buffers Extension generates .idl files containing DDS-XTYPES types equivalent to the Protocol Buffers types defined in .proto files. This conversion enables seamless interoperability between Connext applications using Protocol Buffers data types and those using equivalent DDS-XTYPES, regardless of the programming language used.

1.1.3. Protocol Buffers C++ language binding

Protocol Buffers Extension allows developers to use the C++ message types generated by the protocol buffers compiler (protoc) in combination with Connext’s Modern C++ API. Applications can create DataWriter and DataReader endpoints to exchange objects of the Protocol Buffers types directly over DDS Topics. Existing components that use these types can be easily and efficiently integrated onto the DDS databus.

1.1.4. Integration with DDS

The data types defined using Protocol Buffers are first-class citizens in the Connext platform and can be used just like other DDS types. Full support is provided for features such as type discovery, type matching, type evolution, dynamic types, dynamic data, content filtering, and more.

The .proto files can be enriched with custom Protocol Buffers Extension options defined to control DDS-specific properties, such as indicating key members. Other options allow developers to take advantage of DDS-XTYPES features not natively available in Protocol Buffers. These features enhance the integration of Protocol Buffers Extension components with other Connext applications.

1.2. Components

Protocol Buffers Extension consists of two RTI components and a set of DDS-specific options:

The IDL4 Converter Plugin converts .proto files into equivalent .idl files.
The C++ Code Generator Plugin generates C++ source code from .proto files.
DDS Options for Protocol Buffers types customizes the generated IDL4 types using DDS-specific options defined in .proto files.

1.3. System Requirements

To use Protocol Buffers Extension successfully, your system must meet the following requirements:

Connext Professional is installed on a supported operating system (see Supported Platforms) and the RTI environment variables are set.
The protocol buffer compiler (protoc) is installed and available in your system’s PATH. Protocol Buffers Extension supports protoc versions 3.12.0 through 33.0.
<NDDSHOME>/bin is included in your system’s PATH.
The RTI <NDDSHOME>/resource/proto/omg/dds/descriptor.proto file is available to protoc. This file is included in the Connext installation.

For more detail about these requirements, see Before You Begin.

Protocol Buffers Extension is pre-installed as part of Connext Professional. For instructions to install Connext, see the RTI Connext Professional Installation Guide.

1.4. Paths Mentioned in Documentation

This documentation refers to Connext installation and example paths using the following conventions:

<NDDSHOME> refers to the installation directory for Connext. The default installation paths are:
- macOS® systems: /Applications/rti_connext_dds-<version>
- Linux® systems, non-root user: /home/your user name/rti_connext_dds-<version>
- Linux systems, root user: /opt/rti_connext_dds-<version>
- Windows® systems, user without Administrator privileges: <your home directory>\rti_connext_dds-<version>
- Windows systems, user with Administrator privileges: C:\Program Files\rti_connext_dds-<version>
Whenever you see <NDDSHOME> used in a path, replace it with your installation path. You may also see $NDDSHOME or %NDDSHOME%, which refers to an environment variable set to the installation path.
<path to examples> refers to the directory for Connext example files. By default, examples are copied into your home directory the first time you run RTI Launcher or any script in <NDDSHOME>/bin. This document refers to the location of the copied examples as <path to examples>.

The default paths to the examples are:
- macOS systems: /Users/your user name/rti_workspace/<version>/examples
- Linux systems: /home/your user name/rti_workspace/<version>/examples
- Windows systems: your Windows documents folder\rti_workspace\<version>\examples. Where 'your Windows documents folder' depends on your version of Windows. For example, on Windows 7, the folder is C:\Users\your user name\Documents; on Windows Server 2003, the folder is C:\Documents and Settings\your user name\Documents.
Wherever you see <path to examples>, replace it with the appropriate path.