3. Getting Started

This guide will walk you through the first steps of using RTI Connext TSS. After installation, we recommend building and running the hello_goodbye example application provided with Connext TSS. Before doing so, however, the Connext TSS libraries must be built for your target architecture. Follow the instructions below for a step-by-step guide to both tasks.

Note

This guide assumes that you are building with one of two combinations of architecture and Connext DDS product:

  • Connext DDS Professional 6.1.1.1 on a Red Hat® Enterprise Linux® 8.0 CPU, or

  • Connext DDS Micro 2.4.13.4 on a Deos™ 653 CPU

3.1. Build the Connext TSS Libraries

3.1.1. Prerequisites

  1. Set a JREHOME environment variable to the location of the JRE included with Connext DDS Professional or Micro.

  2. Connext DDS Professional and/or Micro must be installed and built for the target architecture and FACE profile.

3.1.2. Configure the build environment

  1. Download and install CMake.

RTI Connext TSS provides and uses CMake scripts to generate the environment to build its libraries and example applications.

  1. Set an RTITSSHOME environment variable to point to your Connext TSS installation directory.

    For example, if Connext TSS is installed in /home/user/rti/rti_connext_tss-3.1.2/, then set RTITSSHOME (in bash) with this command:

export RTITSSHOME=/home/user/rti/rti_connext_tss-3.1.2

  1. If you are building for Connext DDS Professional, set an NDDSHOME environment variable to point to your Connext DDS installation.

    For example, if Connext DDS is installed in /opt/local/rti/rti_connext_dds-6.1.1.1, then set NDDSHOME (in bash) with this command:

    export NDDSHOME=/opt/local/rti/rti_connext_dds-6.1.1.1

    If you are building with Connext DDS Micro, set an RTIMEHOME environment variable to point to your Connext DDS Micro installation.

    For example, if Connext DDS Micro is installed in /opt/local/rti/rti_connext_micro.2.4.13.4, then set RTIMEHOME (in bash) with this command:

    export RTIMEHOME=/opt/local/rti/rti_connext_micro.2.4.13.4

3.1.3. Set the architecture

If you are building with Connext DDS Professional, set an environment variable RTITSSARCH to the following:

export RTITSSARCH=x64Linux4gcc7.3.0FACE_GP

If you are building with Connext DDS Micro, set RTITSSARCH to the following:

export RTITSSARCH=ppce6500Deos653-10.3.1gcc7.3.0FACE_SB

3.1.4. Build the libraries

  1. Create a build directory:

    cd ${RTITSSHOME}
mkdir build

  2. If you are building with Connext DDS Professional, run CMake with the following command:

    cd build
cmake -DRTI_CONNEXT_TYPE=pro -DRTI_TSS_ENABLE_FACE_COMPLIANCE=GeneralPurpose -DCMAKE_BUILD_TYPE=release -DBUILD_SHARED_LIBS=False -DBUILD_STATIC_LIBS=True ../

    If you are building with Connext DDS Micro, use the following command:

    cd build
cmake -DRTI_CONNEXT_TYPE=micro -DRTI_TSS_ENABLE_FACE_COMPLIANCE=SafetyBase -DCMAKE_BUILD_TYPE=release -DBUILD_SHARED_LIBS=False -DBUILD_STATIC_LIBS=True ../

  3. Build the RTI Connext TSS libraries:

    cmake --build .

3.1.5. Verify the build

A successful build will result in one (statically linked) library:

  • For Connext DDS Professional: ${RTITSSHOME}/lib/${RTITSSARCH}/pro/librti_tsscppz.a

  • For Connext DDS Micro: ${RTITSSHOME}/lib/${RTITSSARCH}/micro/librti_tsscppz.a

The debug library name will have a ‘d’ suffix (e.g. librti_tsscppzd.a).

3.2. Build and run the example applications

Connext TSS ships with example applications that run with either Connext DDS Professional or Connext DDS Micro. They demonstrate how to use the Connext TSS libraries with one or more applications.

The first section below will walk you through the process of building the example hello_goodbye for Connext DDS Professional. The second section covers building hello_goodbye_deos for Connext DDS Micro.

The actual FACE TSS applications include only the minimum necessary code to build a FACE Unit of Portability (UoP) using Connext TSS. The examples demonstrate how a TSS integrator can package additional functionality (plus the Connext TSS plugins) into a linkable library that can be used by a FACE UoP. They also show how to combine multiple connections in the same application and how to set up a callback to process received data.

Note

RTI Connext TSS supports user data types in IDL files only. To convert other FACE data model formats to IDL, contact RTI Support or your local account team for assistance.

Note

RTI Connext TSS contains examples that show interoperablity between TSS and non-TSS RTI products. The examples are the following:

  1. tss_dds_interoperability

  2. tss_micro_interoperability_VxWorks653 (for the VxWorks 653 platform)

  3. hello_goodbye_deos (for the Deos platform with Connext DDS Micro only)

3.2.1. Prerequisites

  1. Build the Connext TSS libraries for the target architecture. Follow the steps in the Build section above.

  2. Set the RTITSSARCH environment variable to the name of the target architecture (x64Linux4gcc7.3.0FACE_GP or ppce6500Deos653-10.3.1gcc7.3.0FACE_SB).

  3. If running with Connext DDS Professional on Linux 8.0, set the NDDSHOME environment variable to the location of the Connext DDS Professional installation.

  4. If running with Connext DDS Micro on Deos 653, set the RTIMEHOME environment variable to the location of the Connext DDS Micro installation.

  5. Set the RTITSSHOME environment variable to the location of the Connext TSS installation.

  6. Set the JREHOME environment variable to the location of the JRE included with Connext DDS Professional or Micro.

  7. Install CMake.

3.2.2. hello_goodbye

3.2.2.1. Build the example

hello_goodbye contains a CMake script to generate the necessary plugins and build the application.

  1. To build the example for Connext DDS Professional on Linux 8.0, run:

    cd ${RTITSSHOME}/examples/hello_goodbye
mkdir build
cd build
cmake -DRTI_CONNEXT_TYPE=<pro> -DRTI_TSS_ENABLE_FACE_COMPLIANCE=GeneralPurpose -DCMAKE_BUILD_TYPE=release ../
cmake --build .

  2. To build the example for Connext DDS Micro on Deos 653, run:

    cd ${RTITSSHOME}/examples/hello_goodbye
mkdir build
cd build
cmake -DRTI_CONNEXT_TYPE=<micro> -DRTI_TSS_ENABLE_FACE_COMPLIANCE=SafetyBase -DCMAKE_BUILD_TYPE=release ../
cmake --build .

  3. The generated plugins will be in the gen directory. The resulting executable is ../bin/${RTITSSARCH}/${RTI_CONNEXT_TYPE}/${CMAKE_BUILD_TYPE}/hello_goodbye_app.

Note

By default, each run of CMake to build this example will call rtiddsgen to replace, or overwrite, all files in the gen directory.

To keep the generated source from being replaced, use the CMake command-line definition -DRTI_REPLACE_GEN=false.

3.2.2.2. Run the example

At this point, you’ve built the TSS library for Connext DDS Professional and linked it with the hello_goodbye example. Now let’s publish and subscribe to data.

By default, the example must be run from the hello_goodbye directory where the default HelloGoodbye_Qos.xml XML QoS configuration file is located. You can set the location of this file in gen/HelloGoodbye_Config.c.

Next, we’ll run the example as a publisher and as a subscriber.

3.2.2.2.1. Run as a publisher

To run the example as a publisher, launch the executable with the -pub command-line option:

./bin/${RTITSSARCH}/${RTI_CONNEXT_TYPE}/${CMAKE_BUILD_TYPE}/hello_goodbye_app -pub

There are two optional arguments:

  1. -num <num samples>: the number of messages to send/receive before exiting.

  2. -id <domain_id>: the Connext DDS domain ID to use.

The publisher’s output will look like this:

------------------------------------
 RTI Connext TSS HelloWorld Example
------------------------------------
Sending unlimited samples ...
sending message 0
sending message 1
sending message 2
sending message 3
sending message 4
sending message 5
3.2.2.2.2. Run as a subscriber

To run the example as a subscriber, use the -sub command-line option:

./bin/${RTITSSARCH}/${RTI_CONNEXT_TYPE}/${CMAKE_BUILD_TYPE}/hello_goodbye_app -sub

There are two optional arguments:

  1. -num <NUM SAMPLES>: the number of messages to send/receive before exiting.

  2. -id <domain_id>: the Connext DDS domain ID to use.

The subscriber does polling reads; the output will look like this:

------------------------------------
 RTI Connext TSS HelloWorld Example
------------------------------------
Receiving unlimited samples ...
received data: id[1] msg[Hello World 1]
received data: id[0] msg[Hello World 2]
received data: id[1] msg[Hello World 3]
received data: id[0] msg[Hello World 4]
received data: id[1] msg[Hello World 5]

Note that if there is no data available, the Receive_Message call will return a FACE::NOT_AVAILABLE error, but the example will continue polling without shutting down.

3.2.3. hello_goodbye_deos

This example is provided as a collection of OpenArbor™ projects. A nai68ppc2 project is included for running the example on real hardware.

Unlike the hello_goodbye example above, which is run both as a publisher and subscriber, this example demonstrates communication between two Connext TSS applications and one Connext DDS Micro application using the ARINC transport.

We will define the following partitions in this example:

  • tss_partition1_application

    Connext TSS application with a publisher connection sending messages to tss_partition2_application.

  • tss_partition2_application

    Connext TSS application with a subscriber connection receiving messages from tss_partition1_application and micro_partition3_app.

  • micro_partition3_app

    Connext DDS Micro application with a publisher sending messages to tss_partition2_application.

Note

The partitions referenced in these instructions are Deos partitions, not Connext DDS partitions.

The code in the gen folders of each partition project was generated from HelloWorld.idl using rtiddsgen.

The SystemConfiguration project links together the three partitions into one system and configures the ARINC 653 environment. The file xml/systemconfig.653.xml specifies the parameters and schedule of the partitions. It also specifies the ARINC ports and channels. Each partition is given a quota for each type of ARINC 653 object. These quotas may need to be increased to support larger applications.

The setupPrintf project creates a shared library with methods for configuring the behavior of printf. This library is used to enable the partitions to print output to the same video stream without overwriting each other.

3.2.3.1. Build the example

  1. Ensure that Connext DDS Micro and Connext TSS have been built for Deos 653.

    See the documentation provided with Connext DDS Micro and Connext TSS for details on the build process.

  2. Open a new OpenArbor workspace.

  3. Go to Window → Preferences and select DDC-I. In the Deos Search Path section, select Add, then navigate to the folder that contains the Connext DDS Micro Library output. Select the folder that contains both the etc and ppc folders. Repeat this process for the Connext TSS Library output.

  4. Import the example projects into a new OpenArbor workspace:

    Go to File → Import → General → Existing Projects into Workspace and select the directory hello_goodbye_deos. Select all seven projects.

    Check the Copy Projects Into Workspace checkbox. Then, click Finish.

  5. For each partition application project, change the paths in “Properties”:

    Right-click the project and select Properties. In the left bar, select DDC-I Options.

    Under C Compile → Directories and C++ Compile → Directories replace the relative paths with the paths to the Connext DDS Micro and Connext TSS include directories.

    Paths that begin with $(PROJECT_DIR.<project name>)/../../include/tss should be replaced with the Connext TSS include paths and paths beginning with $(PROJECT_DIR.<project name>)/../../include/micro should be replaced with the Connext DDS Micro include paths.

  6. Set the IP address of the nai68ppc2 board:

    The network interface is used only to retrieve the application console output. Open the file <nai68ppc2 project>/config/lwip.config.

    In this file, replace the IP address “10.10.30.210” and subnet mask “255.255.0.0” with the IP address and subnet mask of your board.

  7. Build the projects:

    By default, OpenArbor will automatically rebuild each project when changes are detected.

    You can monitor the build progress in the DDC-I Console window. After it finishes, look in the Problems window to make sure there are no errors.

3.2.3.2. Run the example

  1. Copy the necessary files to the TFTP server:

    1. deosBoot.bin from $DESKHOME/platform/nai68ppc2/boot/deosBoot.bin

    2. 68ppc2.dtb from $DESKHOME/platform/nai68ppc2/etc/68ppc2.dtb

    3. hypstart.dkfs from <nai68ppc2 project>/output/hypstart.dkfs

  2. Reboot the board:

    Reboot the board and check the console output to confirm it successfully downloaded the files from the TFTP server and booted.

  3. Create a new remote target:

    Switch to the Target Manager window. Select the option to create a New Remote Target. The Platform Project should be the nai68ppc2 project. Change the Hostname, if necessary, to match the board’s IP address. Click OK.

  4. Check connectivity with the board:

    Expand the menu under the target IP address. Right-click Ping. Click Enable. The text should switch to Ping [pinging] if OpenArbor can communicate with the board. If it says Ping [no ping], then try power-cycling the board and verify its configuration.

  5. Open the Video Stream:

    Expand the menu under the target IP address. Right-click Video Stream. Click Enable. The Video Stream window will open.

  6. Upload the application:

    Right-click the target. Select Update Target Load. Click OK. You should see the application’s output in the Video Stream window.

3.3. Further modifications

This section has tips for modifying the examples bundled with Connext TSS.

3.3.1. Changing QoS

In general, the QoSs for underlying DDS entities are configured in the generated _TSSQosSupport.cpp source files.

3.3.2. Adding connections

Each new connection creates an underlying DDS DataWriter and/or DataReader, so resource limit QoSes may need to be increased for additional connections. See the RESOURCE_LIMITS QoS chapter of the Core Libraries User’s Manual for more information.

3.4. Troubleshooting the examples

This section has tips for working around some common issues.

3.4.1. Function returned an error

The example applications may return an error message of the format:

<function> returned an error: <return_code>

For example, the following error message means FACE::TS::Receive_Message() returned a FACE::RETURN_CODE_TYPE value of 2.

Receive_Message returned an error: 2

The return code can be found in a header file, and the return code of each function can be found in either source or the API Reference documentation.

So for the above example, searching the headers in include/FACE reveals the FACE::RETURN_CODE_TYPE enum in include/FACE/common.hpp, where 2 maps to NOT_AVAILABLE:

typedef enum RETURN_CODE_TYPE
  {
    NO_ERROR ,
    NO_ACTION ,
    NOT_AVAILABLE ,
    ADDR_IN_USE ,
    INVALID_PARAM ,
    INVALID_CONFIG ,
    PERMISSION_DENIED ,
    INVALID_MODE ,
    TIMED_OUT ,
    MESSAGE_STALE ,
    CONNECTION_IN_PROGRESS ,
    CONNECTION_CLOSED ,
    DATA_BUFFER_TOO_SMALL
  } RETURN_CODE_TYPE;