.. include:: vars.rst .. _section-gettingstarted: Getting Started with Connext TSS ******************************** After :ref:`installing ` and :ref:`building ` |TSS| for your target architecture, you can run the provided example FACE application to understand how to use the |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 :ref:`the API Reference `. .. _section-examples: Build and Run the Example Application ===================================== |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 |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 |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 ``\examples``. Detailed information about the example source code is included in the readme for each supported OS. .. note:: |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. 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 :ref:`building the TSS libraries `. - ``RTI_CONNEXT_TYPE`` - ``RTI_TSS_ENABLE_FACE_COMPLIANCE`` - ``CMAKE_BUILD_TYPE`` 1. To build the example, run the following commands: .. code-block:: bash cd ${RTITSSHOME}/examples///hello_goodbye mkdir build cd build cmake -DRTI_CONNEXT_TYPE= -DRTI_TSS_ENABLE_FACE_COMPLIANCE= -DCMAKE_BUILD_TYPE= ../ cmake --build . Alternatively, use cmake-gui to configure additional CMake settings. .. code-block:: bash cd ${RTITSSHOME}/examples///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|, 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``. 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 |PUB| and as a |SUB|. 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. Run as Publisher ^^^^^^^^^^^^^^^^ To run the example as a |PUB|, launch the executable with the ``-pub`` command-line option: .. code-block:: bash ./bin/${RTITSSARCH}/${RTI_CONNEXT_TYPE}/${CMAKE_BUILD_TYPE}/hello_goodbye_app -pub There is one optional argument, ``-num ``; this is the number of messages to send/receive before exiting. The |PUB| output will look like this: .. code-block:: bash --------------------------------------------------- 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 Run as Subscriber ^^^^^^^^^^^^^^^^^ To run the example as a |SUB|, use the ``-sub`` command-line option: .. code-block:: bash ./bin/${RTITSSARCH}/${RTI_CONNEXT_TYPE}/${CMAKE_BUILD_TYPE}/hello_goodbye_app -sub There is one optional argument, ``-num ``: this is the number of messages to send/receive before exiting. The output of a |SUB| doing polling reads looks like this: .. code-block:: bash --------------------------------------------------- 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 |SUB| in callback mode, use the ``+sub`` command-line option: .. code-block:: bash ./bin/${RTITSSARCH}/${RTI_CONNEXT_TYPE}/${CMAKE_BUILD_TYPE}/hello_goodbye_app +sub Its output will look like this: .. code-block:: bash --------------------------------------------------- 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. Modify Example ============== Optionally, you can modify the example bundled with |TSS| as noted below. Changing QoS ------------ To change the QoS for the underlying DDS *Entities*, configure the generated ``_TSSQosSupport.cpp`` source file as needed. Adding Connections ------------------ Each new connection creates an underlying DDS |DW| and/or |DR|, 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. Troubleshooting the Example =========================== This section has tips for working around common issues. Function Returned an Error -------------------------- The example applications may return an error message in the following format: .. code-block:: none returned an error: For example, the following error message means ``FACE::TS::Base::Receive_Message()`` returned a ``FACE::RETURN_CODE_TYPE`` value of 2. .. code-block:: none 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 :ref:`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``: .. code-block:: C++ 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;