3.21. Example Applications

The RTI Code Generator (rtiddsgen) can generate example applications from an IDL file, as shown in Hello World with Publish/Subscribe. The last type in the IDL is used as the data-type to publish. Refer to Generating examples for instructions on how to build these examples.

Connext Micro also provides some buildable applications in the installation directory, as described in Provided examples.

3.21.1. Generating examples

Note

Before running rtiddsgen, you might need to add rti_connext_dds-<version>/rtiddsgen/scripts to your path environment variable folder.

3.21.1.1. Default example

To generate an example, run the following command:

rtiddsgen -example -language <C|C++> [-namespace] <file with type definition>

This generates an example using the default example template, which uses the Dynamic Participant Dynamic Endpoint (DPDE) discovery plugin.

rtiddsgen accepts the following options:

  • -example: Generates type files, example files, and CMakelists files.

  • -language <C|C++>: Generates C or C++ code.

  • -namespace: Enables C++ namespaces when the language option is C++.

The generated example can then be compiled using CMake and the CMakelists.txt file generated by Code Generator. Code Generator also creates a README.txt file with a description of the example and instructions for how to compile and run it.

3.21.1.2. Custom example

Code Generator can also generate examples using custom templates with the option -exampleTemplate <templateName>.

To generate an example using a custom template instead of the default one, run the following command:

rtiddsgen -example -exampleTemplate <template name> -language <C|C++> [-namespace] <file with type definition>

To see the list of the available templates for each language, run the following command:

rtiddsgen -showTemplates

The output will be similar to the following:

List of example templates per language:
    - C:
        - cert
        - dpse
        - shared_memory
        - static_udp
        - waitsets
        - crc
        - zcv2
        - mag/shared_memory
        - mag/static_udp
        - mag/dpde
        - mag/dpse
        - mag/cert/dpse
        - psk
        - content_filter
        - custom_filter
        - cert_custom_filter
        - cert_psk
    - C++:
        - dpse
        - waitsets
        - mag/dpde
    - C++ Namespace:
        - dpse
        - waitsets

As an example, the following command will generate an example in the C language, using the waitsets custom template instead of the default template:

rtiddsgen -example -exampleTemplate waitsets -language C <file with type definition>

3.21.1.3. Descriptions of generated examples

Each example consists of a publication and subscription pair to send and receive samples of the type specified by the user. When compiled, the example creates two applications: one to send samples (a publisher) and another to receive samples (a subscriber).

  • default example (no template specified)

    Discovery of endpoints is done with the Dynamic Discovery Plugin (DPDE). Only the UDP and INTRA transports are enabled. The subscriber application creates a DataReader, which uses a listener to receive notifications about new samples and matched publishers. These notifications are received in the middleware thread (instead of the application thread).

  • cert

    An example that only uses APIs that are compatible with Connext Cert.

  • dpse

    Discovery of endpoints is done with the Static Discovery Plugin (DPSE). Static-endpoint discovery uses function calls to statically assert information about remote endpoints belonging to remote DomainParticipants.

    The following template variable can be passed with -V to configure the generated example:

    • use_autoenable_entities=false: Disables auto-enabling of DDS entities on creation. An explicit Application_enable() call is generated and invoked after all static discovery assertions are made, so that communication begins only once the application is fully configured.

  • shared_memory

    The only transport used is shared memory. Because the UDP Transport is disabled and only the Shared Memory Transport (SHMEM) is enabled, both the publisher and subscriber applications need to run in the same operating system instance.

  • static_udp

    This example uses a static UDP Transport interface configuration. Using this API, the UDP transport is statically configured. This is useful in systems that are not able to return the installed UDP interfaces (name, IP address, mask, etc.).

  • waitsets

    In this example, the Subscriber application creates a DataReader that uses a Waitset (instead of a listener) to receive notifications about new samples and matched publishers. These notifications are received in the middleware thread (instead of the application thread).

  • crc

    This example includes configuration of the Message Integrity Checking settings. The CRC fields in the WireProtocolQosPolicy enable the generation of a checksum value based on the data being transmitted. They also determine which checksums are allowed and whether they should be sent.

  • zcv2

    This example uses the Zero Copy v2 Transport and handles discovery over the UDP Transport. User traffic is handled using the Zero Copy v2 transport.

  • mag/

    These examples create an example XML application file and an example Qos profile file and then use Application Generation Using XML to generate the application from the XML and Qos file.

    The following template variable can be passed with -V to configure the generated example:

    • use_autoenable_entities=false: Disables auto-enabling of DDS entities on creation. An explicit Application_enable() call is generated and invoked after all static discovery assertions are made, so that communication begins only once the application is fully configured.

  • psk

    This example uses pre-shared key (PSK) encryption to secure communications. You must have the Lightweight Security Plugin installed in order to compile this example.

  • content_filter

    This example demonstrates how to use content filtering with the builtin SQL content filter and Dynamic Discovery Plugin (DPDE). The subscriber application configures the DataReader QoS to filter samples using an SQL expression, and the publisher application enables writer-side filtering.

  • custom_filter

    This example demonstrates how to use content filtering with a custom content filter and Dynamic Discovery Plugin (DPDE). The subscriber application configures the DataReader QoS to filter samples using a custom content filter, and the publisher application enables writer-side filtering.

  • cert_custom_filter

    This example demonstrates how to use content filtering with a custom content filter, Connext Cert, and Static Discovery Plugin (DPSE). The subscriber application configures the DataReader QoS to filter samples using a custom content filter. The publisher application enables writer-side filtering and manually asserts the content filter parameters used by the subscriber.

  • cert_psk

    This example only uses APIs compatible with Connext Cert and uses pre-shared key (PSK) encryption to secure communications. Discovery of endpoints is done with the Static Discovery Plugin (DPSE). You must have the Lightweight Security Plugin installed in order to compile this example.

3.21.1.4. How to compile and run the generated examples

Before compiling, set the environment variable RTIMEHOME to the Connext Micro installation directory. Your Connext Micro directory includes rtime-make (on Linux® and macOS® systems) or rtime-make.bat (on Windows® systems) to simplify invocation of CMake. This script requires RTIMEHOME to be set and is a convenient way to invoke CMake with the correct options.

Consult the README.txt file in the generated example directory for detailed instructions on compiling and running your application.

Warning

We recommend using the toolchain file that matches the target architecture to compile the generated examples.

For example, if the target architecture is --target armv8leElfgcc13.3.0-Linux6, then the example applications should be compiled with the armv8leElfgcc13.3.0-Linux6 toolchain file. Failing to do so may cause warnings.

3.21.2. Provided examples

Connext Micro provides buildable example applications in the example/ directory of your installation. Each example demonstrates different features, as described below:

  • HelloWorld_transformations: A HelloWorld example that uses UDP transformations to send encrypted packets using OpenSSL.

  • HelloWorld_dgram: A HelloWorld example that uses an example DGRAM implementation.

Consult the README.txt file included with each example for instructions on how to build and run the application.