.. include:: vars.rst .. _section-gettingstarted: Getting Started *************** This guide will walk you through the first steps of using |RTI_TSS|. After installation, we recommend building and running the ``hello_goodbye`` example application provided with |TSS|. Before doing so, however, the |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| product: * |CONNEXT| *Professional* 6.1.1.1 on a Red Hat® Enterprise Linux® 8.0 CPU, or * |CONNEXT_MICRO| 2.4.13.4 on a Deos™ 653 CPU Build the |TSS_HEADING| Libraries --------------------------------- Prerequisites ............. #. Set a ``JREHOME`` environment variable to the location of the JRE included with |CONNEXT| *Professional* or *Micro*. #. |CONNEXT| *Professional* and/or *Micro* must be installed and built for the target architecture and FACE profile. Configure the build environment ............................... 1. Download and install `CMake `_. |RTI_TSS| provides and uses CMake scripts to generate the environment to build its libraries and example applications. 2. Set an ``RTITSSHOME`` environment variable to point to your |TSS| installation directory. For example, if |TSS| is installed in ``/home/user/rti/rti_connext_tss-3.1.2/``, then set *RTITSSHOME* (in bash) with this command: .. code-block:: bash export RTITSSHOME=/home/user/rti/rti_connext_tss-3.1.2 3. If you are building for |CONNEXT| *Professional*, set an *NDDSHOME* environment variable to point to your |CONNEXT| installation. For example, if |CONNEXT| is installed in ``/opt/local/rti/rti_connext_dds-6.1.1.1``, then set *NDDSHOME* (in bash) with this command: .. code-block:: bash export NDDSHOME=/opt/local/rti/rti_connext_dds-6.1.1.1 If you are building with |CONNEXT_MICRO|, set an *RTIMEHOME* environment variable to point to your |CONNEXT_MICRO| installation. For example, if |CONNEXT_MICRO| is installed in ``/opt/local/rti/rti_connext_micro.2.4.13.4``, then set *RTIMEHOME* (in bash) with this command: .. code-block:: bash export RTIMEHOME=/opt/local/rti/rti_connext_micro.2.4.13.4 Set the architecture .................... If you are building with |CONNEXT| *Professional*, set an environment variable *RTITSSARCH* to the following: .. code-block:: bash export RTITSSARCH=x64Linux4gcc7.3.0FACE_GP If you are building with |CONNEXT_MICRO|, set *RTITSSARCH* to the following: .. code-block:: bash export RTITSSARCH=ppce6500Deos653-10.3.1gcc7.3.0FACE_SB Build the libraries ................... 1. Create a build directory: .. code-block:: bash cd ${RTITSSHOME} mkdir build 2. If you are building with |CONNEXT| *Professional*, run CMake with the following command: .. code-block:: bash 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_MICRO|, use the following command: .. code-block:: bash 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_TSS| libraries: .. code-block:: bash cmake --build . Verify the build ................ A successful build will result in one (statically linked) library: * For |CONNEXT| *Professional*: ``${RTITSSHOME}/lib/${RTITSSARCH}/pro/librti_tsscppz.a`` * For |CONNEXT_MICRO|: ``${RTITSSHOME}/lib/${RTITSSARCH}/micro/librti_tsscppz.a`` The debug library name will have a 'd' suffix (e.g. ``librti_tsscppzd.a``). .. _section-examples: Build and run the example applications -------------------------------------- |TSS| ships with example applications that run with either |CONNEXT| *Professional* or |CONNEXT_MICRO|. They demonstrate how to use the |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| *Professional*. The second section covers building ``hello_goodbye_deos`` for |CONNEXT_MICRO|. The actual FACE TSS applications include only the minimum necessary code to build a FACE Unit of Portability (UoP) using |TSS|. The examples demonstrate how a TSS integrator can package additional functionality (plus the |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_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_TSS| contains examples that show interoperablity between TSS and non-TSS RTI products. The examples are the following: #. tss_dds_interoperability #. tss_micro_interoperability_VxWorks653 (for the VxWorks 653 platform) #. hello_goodbye_deos (for the Deos platform with |CONNEXT_MICRO| only) Prerequisites ............. #. Build the |TSS| libraries for the target architecture. Follow the steps in the :ref:`section-build` section above. #. Set the ``RTITSSARCH`` environment variable to the name of the target architecture (x64Linux4gcc7.3.0FACE_GP or ppce6500Deos653-10.3.1gcc7.3.0FACE_SB). #. If running with |CONNEXT| *Professional* on Linux 8.0, set the ``NDDSHOME`` environment variable to the location of the |CONNEXT| *Professional* installation. #. If running with |CONNEXT_MICRO| on Deos 653, set the ``RTIMEHOME`` environment variable to the location of the |CONNEXT_MICRO| installation. #. Set the ``RTITSSHOME`` environment variable to the location of the |TSS| installation. #. Set the ``JREHOME`` environment variable to the location of the JRE included with |CONNEXT| *Professional* or *Micro*. #. Install `CMake `_. hello_goodbye ............. 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| *Professional* on Linux 8.0, run: .. code-block:: bash cd ${RTITSSHOME}/examples/hello_goodbye mkdir build cd build cmake -DRTI_CONNEXT_TYPE= -DRTI_TSS_ENABLE_FACE_COMPLIANCE=GeneralPurpose -DCMAKE_BUILD_TYPE=release ../ cmake --build . 2. To build the example for |CONNEXT_MICRO| on Deos 653, run: .. code-block:: bash cd ${RTITSSHOME}/examples/hello_goodbye mkdir build cd build cmake -DRTI_CONNEXT_TYPE= -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``. Run the example ^^^^^^^^^^^^^^^ At this point, you've built the TSS library for |CONNEXT| *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. Run as a publisher '''''''''''''''''' To run the example as a publisher, 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 are two optional arguments: 1. ``-num ``: the number of messages to send/receive before exiting. 2. ``-id ``: the |CONNEXT| domain ID to use. The publisher's output will look like this: .. code-block:: bash ------------------------------------ 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 Run as a subscriber ''''''''''''''''''' To run the example as a subscriber, use the ``-sub`` command-line option: .. code-block:: bash ./bin/${RTITSSARCH}/${RTI_CONNEXT_TYPE}/${CMAKE_BUILD_TYPE}/hello_goodbye_app -sub There are two optional arguments: 1. ``-num ``: the number of messages to send/receive before exiting. 2. ``-id ``: the |CONNEXT| domain ID to use. The subscriber does polling reads; the output will look like this: .. code-block:: bash ------------------------------------ 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. 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 |TSS| applications and one |CONNEXT_MICRO| application using the ARINC transport. We will define the following partitions in this example: * ``tss_partition1_application`` |TSS| application with a publisher connection sending messages to ``tss_partition2_application``. * ``tss_partition2_application`` |TSS| application with a subscriber connection receiving messages from ``tss_partition1_application`` and ``micro_partition3_app``. * ``micro_partition3_app`` |CONNEXT_MICRO| application with a publisher sending messages to ``tss_partition2_application``. .. note:: The partitions referenced in these instructions are Deos partitions, not |CONNEXT| 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. Build the example ^^^^^^^^^^^^^^^^^ 1. Ensure that |CONNEXT_MICRO| and |TSS| have been built for Deos 653. See the documentation provided with |CONNEXT_MICRO| and |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_MICRO| Library output. Select the folder that contains both the ``etc`` and ``ppc`` folders. Repeat this process for the |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_MICRO| and |TSS| include directories. Paths that begin with ``$(PROJECT_DIR.)/../../include/tss`` should be replaced with the |TSS| include paths and paths beginning with ``$(PROJECT_DIR.)/../../include/micro`` should be replaced with the |CONNEXT_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 ``/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. Run the example ^^^^^^^^^^^^^^^ 1. Copy the necessary files to the TFTP server: a. ``deosBoot.bin`` from ``$DESKHOME/platform/nai68ppc2/boot/deosBoot.bin`` b. ``68ppc2.dtb`` from ``$DESKHOME/platform/nai68ppc2/etc/68ppc2.dtb`` c. ``hypstart.dkfs`` from ``/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. Further modifications --------------------- This section has tips for modifying the examples bundled with |TSS|. Changing QoS ............ In general, the QoSs for underlying DDS entities are configured in the generated ``_TSSQosSupport.cpp`` source files. 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. Troubleshooting the examples ---------------------------- This section has tips for working around some common issues. Function returned an error .......................... The example applications may return an error message of the format: .. code-block:: none returned an error: For example, the following error message means ``FACE::TS::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. 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``: .. 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;