4. Getting Started

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. Building and Running the Example Application

Connext TSS ships with an example application that runs with Connext Micro or Connext Professional. 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 Unit of Portability (UoP). 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 (Connext Micro or Connext Professional) or C++ (Connext Micro). 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. Building 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) or Connext Professional (GeneralPurpose only). 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

• BUILD_SHARED_LIBS (optional)

1. To build the example, run the following commands:

   cd ${RTITSSHOME}/examples/<C_Examples|C++_Examples>/<micro|pro>/<Linux|Windows>/hello_goodbye
   mkdir build
   cd build
   cmake -DRTI_CONNEXT_TYPE=<micro|pro> -DRTI_TSS_ENABLE_FACE_COMPLIANCE=<GeneralPurpose|SafetyBase> -DCMAKE_BUILD_TYPE=<Release|Debug> ../
   cmake --build .
   

   Note

   When building for Windows systems, Visual Studio will default to Debug even when Release is specified in the first CMake command above. To build Release, add --config Release to the second CMake command above.

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

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

2. 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/Connext Professional, 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. Running the example

At this point, you’ve built the TSS library for Connext Micro or Connext Professional 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. Running 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 is one optional argument, -num <NUM SAMPLES>; this is the number of messages to send/receive before exiting.

The Publisher output will look similar to 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. Running 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 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 similar to 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 similar to 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/HelloWorld/TypedTS_Impl.c or gen/FACE/TSS/HelloWorld/TypedTS_Impl.cpp) prints the same default message for each received sample. The generated callback handler(s) should be manually modified as necessary for your application.

4.1.2.3. Running as both publisher and subscriber

Note

This option is only available in Connext Micro examples.

To run both a Publisher and Subscriber within the same process, use the -pubsub command-line option:

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

This mode initializes the TSS stack once, creates separate publisher and subscriber connections (each with its own connection ID), and spawns two POSIX threads — one for publishing and one for subscribing — that run concurrently.

Use -num <NUM SAMPLES> to limit the number of messages sent and received:

./bin/${RTITSSARCH}/${RTI_CONNEXT_TYPE}/${CMAKE_BUILD_TYPE}/hello_goodbye_app -pubsub -num 10

The output will show interleaved send and receive messages similar to this:

---------------------------------------------------
 RTI Connext TSS HelloWorld Example (Connext Micro)
---------------------------------------------------
sending message 0
sending message 1
received data: id[1] msg[Hello World 0] ...
sending message 2
received data: id[0] msg[Hello World 1] ...

If -num is not specified, both the publisher and subscriber will run indefinitely until the process is interrupted (e.g., with Ctrl+C).

4.2. Modifying the 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 or _TSSQosSupport.c 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 in 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 or include/FACE/Common.h, where 2 maps to NOT_AVAILABLE:

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