4. Getting Started with Connext TSS

After installing and building Connext TSS for your target architecture, you can run the provided example FACE application to understand how to use the Connext TSS libraries with a FACE application.

Note

This example provides a basic FACE logger that prints any log message sent to it regardless of logging level. You can choose to modify the example or provide your own logger. For more information about logging, see the API Reference.

4.1. Build and Run the Example Application

Connext TSS ships with an example application that runs with Connext Micro. The example, hello_goodbye, demonstrates 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 (Unit of Portability). It also shows how to combine multiple connections in the same application and how to set up a callback to process received data. The application includes only the minimum necessary code to build a FACE UoP using Connext TSS.

The following sections step you through how to build and run the example for Linux and Windows using C. To build the example for LynxOS or VxWorks, refer to the readme file for your language and OS at <RTITSSHOME>\examples. Detailed information about the example source code is included in the readme for each supported OS.

Note

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.

4.1.1. Build the Example

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

The example can be compiled against Connext Micro (GeneralPurpose and SafetyBase profiles). Out of the box, an application compiled with the GeneralPurpose profile will not communicate with an application compiled with the SafetyBase profile.

When invoking CMake, use the same variables as when building the TSS libraries.

RTI_CONNEXT_TYPE
RTI_TSS_ENABLE_FACE_COMPLIANCE
CMAKE_BUILD_TYPE

To build the example, run the following commands:

cd ${RTITSSHOME}/examples/<C_Examples|C++_Examples>/<Linux_or_Windows>/hello_goodbye
mkdir build
cd build
cmake -DRTI_CONNEXT_TYPE=<micro> -DRTI_TSS_ENABLE_FACE_COMPLIANCE=<GeneralPurpose/SafetyBase> -DCMAKE_BUILD_TYPE=<your_build_type> ../
cmake --build .

Alternatively, use cmake-gui to configure additional CMake settings.

cd ${RTITSSHOME}/examples/<C_Examples|C++_Examples>/<Linux_or_Windows>/hello_goodbye
mkdir build_gui
cd build_gui
cmake-gui ../
cmake --build .

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

Each build is for a single combination of Connext Micro, FACE profile, and CMake build type. Additional builds for different configuration combinations are best done out-of-source (i.e., from a directory separate from the source, like the build or build-gui directories created in step 1 above). However, note that the resulting applications are copied to the same output directory.

Note

By default, each run of CMake to build this example calls 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.

4.1.2. Run the Example

At this point, you’ve built the TSS library for Connext Micro and linked it with the hello_goodbye example. Next, you’ll run the example as a Publisher and as a Subscriber.

By default, the example must be run from the hello_goodbye directory where the default TSS.xml TSS configuration file is located. If you want to run the example from a different directory, set the XML file location in the corresponding configuration files in the app directory.

4.1.2.1. Run as 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 is one optional argument, -num <NUM SAMPLES>; this is the number of messages to send/receive before exiting.

The Publisher output will look like this:

---------------------------------------------------
 RTI Connext TSS HelloWorld Example (Connext Micro)
---------------------------------------------------
Sending unlimited samples ...
sending message 0
sending message 1
sending message 2
sending message 3
sending message 4
sending message 5

4.1.2.2. Run as 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 is one optional argument, -num <NUM SAMPLES>: this is the number of messages to send/receive before exiting.

The output of a Subscriber doing polling reads looks like this:

---------------------------------------------------
 RTI Connext TSS HelloWorld Example (Connext Micro)
---------------------------------------------------
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 (ordinal value is 2), but the example will continue polling without shutting down.

Alternatively, to run a Subscriber in callback mode, use the +sub command-line option:

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

Its output will look like this:

---------------------------------------------------
RTI Connext TSS HelloWorld Example (Connext Micro)
---------------------------------------------------
Receiving unlimited samples ...
[FACE::DM::RTI::HelloWorld Callback_Handler called]
[FACE::DM::RTI::HelloWorld Callback_Handler called]
[FACE::DM::RTI::HelloWorld Callback_Handler called]

Note that the generated callback handler (in gen/FACE/TSS/RTI/HelloWorld/TypedTS_Impl.c) prints the same default message for each received sample. The generated callback handler(s) should be manually modified as necessary for your application.

4.2. Modify Example

Optionally, you can modify the example bundled with Connext TSS as noted below.

4.2.1. Changing QoS

To change the QoS for the underlying DDS Entities, configure the generated _TSSQosSupport.cpp source file as needed.

4.2.2. Adding Connections

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

4.3. Troubleshooting the Example

This section has tips for working around common issues.

4.3.1. Function Returned an Error

The example applications may return an error message in the following format:

<function> returned an error: <return_code>

For example, the following error message means FACE::TS::Base::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.

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;