.. include:: vars.rst .. _section-Tutorials: Tutorials ********* This chapter describes several examples, all of which use *RTI* |SHAPESDEMO| to publish and subscribe to topics which are colored moving shapes. |SHAPESDEMO| is installed automatically with |RTI_CONNEXT| Professional. You'll find it in *RTI Launcher*'s Learn tab. In each example, you can start all the applications on the same computer or on different computers in your network. Important Notes: - Please review :ref:`section-Introduction-Paths` to understand where to find the examples (referred to as ). - The following instructions include commands that you will enter in a command shell. These instructions use forward slashes in directory paths, such as ``bin/rtiroutingservice``. If you are using a Windows platform, replace all forward slashes in such paths with backwards slashes, such as ``bin\rtiroutingservice``. - If you run |SHAPESDEMO| and |RS| on different machines and these machines do not communicate over multicast, you will have to set the environment variable ``NDDS_DISCOVERY_PEERS`` to enable communication. For example, assume that you run |RS| on Host 1 and |SHAPESDEMO| on Host 2 and Host 3. In this case, the environment variable would be set as follows: .. rubric:: Host 1 .. tabs:: .. group-tab:: Linux/macOS .. code-block:: console $ export NDDS_DISCOVERY_PEERS=, .. group-tab:: Windows .. code-block:: doscon > set NDDS_DISCOVERY_PEERS=, .. rubric:: Host 2 .. tabs:: .. group-tab:: Linux/macOS .. code-block:: console $ export NDDS_DISCOVERY_PEERS= .. group-tab:: Windows .. code-block:: doscon > set NDDS_DISCOVERY_PEERS= .. rubric:: Host 3 .. tabs:: .. group-tab:: Linux/macOS .. code-block:: console $ export NDDS_DISCOVERY_PEERS= .. group-tab:: Windows .. code-block:: doscon > set NDDS_DISCOVERY_PEERS= .. _section-StartingShapesDemo: Starting Shapes Demo ====================== You can start *Shapes Demo* from the Learn tab in *RTI Launcher*. .. figure:: static/ShapesDemoLauncher.png :alt: Open the Shapes Demo tool from Launcher :name: FigureShapesDemoLauncher :align: center :figwidth: 60 % Or from a command shell: .. tabs:: .. group-tab:: Linux/macOS .. code-block:: console $ NDDSHOME/bin/rtishapesdemo .. group-tab:: Windows .. code-block:: doscon > %NDDSHOME%\bin\rtishapesdemo NDDSHOME is described in :ref:`section-Introduction-Paths`. .. _section-Tutorials-ExampleSingleTopic: Example: Routing a single specific Topic ======================================== This example routes the samples for the *Topic* ``Square`` from domain 0 to 1. #. Start |SHAPESDEMO| on domain 0 and publish squares. We'll call this the Publishing Demo. #. Start another instance of |SHAPESDEMO| but this time on domain 1, and subscribe to squares. We'll call this the Subscribing Demo. Notice that the Subscribing Demo does not receive any shapes since we haven’t started |RS| yet. #. Get the example configuration :download:`rti_rs_example_square_topic.xml <../example/shapes/rti_rs_example_square_topic.xml>`. and place it into your working directory. #. Run |RS| by entering the following in a command shell: .. code-block:: console $ cd $ bin/rtiroutingservice \ -cfgFile rti_rs_example_square_topic.xml \ -cfgName SquaresRouter \ -verbosity LOCAL Now you should see all the shapes in the Subscribing Demo. #. Stop |RS| by pressing ``Ctrl-c`` .. _section-Tutorials-ExampleAllTopics: Example: Routing All Data from One Domain to Another ==================================================== This example uses the default configuration file [#f1]_ for |RS|, which routes all data published on domain 0 to subscribers on domain 1. #. Start |SHAPESDEMO|. We'll call this the Publishing Demo. It uses domain ID 0. #. Start a second copy of |SHAPESDEMO|. We'll call this the Subscribing Demo. Then: * Open its Configuration dialog (under Controls). * Press **Stop**. * Change the domain ID to 1. * Press **Start**. #. In the Publishing Demo, publish some Squares, Circles, and Triangles. #. In the Subscribing Demo, subscribe to Squares, Circles, and Triangles. Notice that the Subscribing Demo does not receive any shapes. Since we haven’t started |RS| yet, data from domain 0 isn’t routed to domain 1. #. Start |RS| by entering the following in a command shell: .. code-block:: console cd bin/rtiroutingservice -cfgName default Now you should see all the shapes in the Subscribing Demo. #. Stop |RS| by pressing **Ctrl-c**. You should see that the Subscribing Demo stops receiving shapes. Additionally, you can start |RS| (Step 5) with the following parameters: - **-verbosity 3**, to see messages from |RS| including events that have triggered the creation of routes. - **-domainIdBase** *X*, to use domains *X* and *X+1* instead of 0 and 1 (in this case, you need to change the domain IDs used by |SHAPESDEMO| accordingly). This option adds X to the domain IDs in the configuration file. .. note:: **-domainIdBase** only affects the domain IDs of DomainRoute participants; it does not affect the domain IDs of participants used for monitoring or administration. .. rubric: .. [#f1] /resource/xml/RTI_ROUTING_SERVICE.xml .. _section-Tutorials-Example2: Example: Changing Data to a Different Topic of Same Type ======================================================== In this example, |RS| receives samples of topic Square and republishes them as samples of topic Circle. #. Start |SHAPESDEMO|. We'll call this the Publishing Demo. It uses domain ID 0. #. Start a second copy of |SHAPESDEMO|. We'll call this the Subscribing Demo. Then: * Open its Configuration dialog (under Controls). * Press **Stop**. * Change the domain ID to 1. * Press **Start**. #. In the Publishing Demo, publish some Squares, Circles, and Triangles. #. In the Subscribing Demo, subscribe to Squares, Circles, and Triangles. Notice that the subscriber does not receive any samples, because the publisher and subscriber are in different domains. #. Start |RS| by entering the following in a command shell: .. code-block:: console cd bin/rtiroutingservice -cfgFile /routing_service/shapes/topic_bridge.xml \ -cfgName example Notice that the Subscribing Demo only receives Circles, which match the movement of the Squares being published by the Publishing Demo. This is because the Squares are being republished as topic Circle. #. Stop |RS| by pressing **Ctrl-c**. #. Try writing your own topic route that republishes triangles on Domain 0 to circles on Domain 1. Create some Triangle publishers and a Circle subscriber in the respective |SHAPESDEMO| windows. .. _section-Tutorials-Example3: Example: Changing Some Values in Data ===================================== So far, we have learned how to route samples from one topic to another topic of the same data type. Now we will see how to change the value of some fields in the samples and republish them. #. Start |SHAPESDEMO|. We'll call this the Publishing Demo. It uses domain ID 0. #. Start a second copy of |SHAPESDEMO|. We'll call this the Subscribing Demo. Then: * Open its Configuration dialog (under Controls). * Press **Stop**. * Change the domain ID to 1. * Press **Start**. #. In the Publishing Demo, publish some Squares, Circles, and Triangles. #. Start |RS| by entering the following in a command shell: .. code-block:: console cd bin/rtiroutingservice -cfgFile /routing_service/shapes/topic_bridge_w_transf1.xml \ -cfgName example #. In the Subscribing Demo, subscribe to Squares, Circles, and Triangles. Notice that the (x,y) coordinates of the shapes are inverted form what appears in the Publishing Demo. #. Stop |RS| by pressing **Ctrl-c**. #. Try changing the transformation to assign the output **shapesize** to the input **x**. .. _section-Tutorials-Example4: Example: Transforming the Data's Type and Topic with an Assignment Transformation ================================================================================= This example shows how to transform the data topic and type. We will use |RTISPY| to verify the result. |RTISPY| is a utility provided with |CONNEXT|; it monitors publications on any DDS domain. #. Start |SHAPESDEMO|. We'll call this the Publishing Demo. It uses domain ID 0. #. In the Publishing Demo, publish some Squares. #. Start |RS| by entering the following in a command shell: .. code-block:: console cd bin/rtiroutingservice -cfgFile /routing_service/shapes/topic_bridge_w_transf2.xml \ -cfgName example #. We will use the |RTISPY| utility to verify the transformation of the data topic and type. Run these commands: .. code-block:: console cd bin/rtiddsspy -domainId 0 -printSample bin/rtiddsspy -domainId 1 -printSample You will notice that the publishing samples received by |RTISPY| for domain 0 are of type ShapeType and topic Square. The subscribing samples received by |RTISPY| for domain 1 are of type Point and topic Position. Notice that the two data structures are different. #. Stop |RS| by pressing **Ctrl-c**. .. _section-Tutorials-CustomTransf: Example: Transforming the Data with a Custom Transformation =========================================================== Now we will use our own transformation between shapes. |RS| allows you to install plug-ins that implement the Transformation API to create custom transformations. To build a custom transformation, you must have the |CONNEXT| libraries installed. .. note:: This example assumes your working directory is /routing_service/shapes/transformation/[make or windows]. If your working directory is different, you will need to modify the configuration topic_bridge_w_custom_transf.xml to update the paths. #. Compile the transformation in /routing_service/shapes/transformation/[make or windows]: - On Linux/macOS systems: - Set the environment variable NDDSHOME (see :ref:`section-Introduction-Paths`). An easy way to do this is to run *rtisetenv*: ``$ source /resource/scripts/rtisetenv_.bash``. (For more information about *rtisetenv*, see :link_doc_gsg_setenv_s:`Set Up Environment Variables (rtisetenv), in the RTI Connext DDS Getting Started Guide `.) - Enter: .. code-block:: console cd /routing_service/shapes/transformation/make gmake -f Makefile. - On Windows systems: - Set the environment variable NDDSHOME (see :ref:`section-Introduction-Paths`). An easy way to do this is to run *rtisetenv*: ``> \resource\scripts\rtisetenv_.bat``. (For more information about *rtisetenv*, see :link_doc_gsg_setenv_s:`Set Up Environment Variables (rtisetenv), in the RTI Connext DDS Getting Started Guide `.) - Open the Visual Studio solution under \\routing_service\\shapes\\transformation\\windows. - Select the Release DLL build mode and build the solution. #. Start |SHAPESDEMO|. We'll call this the Publishing Demo. It uses domain ID 0. #. In the Publishing Demo, publish some Squares. #. Start |RS| by entering the following in a command shell: .. code-block:: console cd bin/rtiroutingservice -cfgFile /routing_service/shapes/topic_bridge_w_custom_transf.xml \ -cfgName example #. Start a second copy of |SHAPESDEMO|. We'll call this the Subscribing Demo. Then: * Open its Configuration dialog (under Controls). * Press **Stop**. * Change the domain ID to 1. * Press **Start**. #. In the Subscribing Demo, subscribe to Squares. Notice that squares on domain 1 have only two possible values for **x**. #. Stop |RS| by pressing **Ctrl-c**. #. Change the fixed ‘x’ values for the Squares in the configuration file and restart |RS|. #. Stop |RS| by pressing **Ctrl-c**. #. Edit the source code (in shapestransf.c) to make the transformation multiply the value of the field by the given integer constant instead of assigning the constant. .. hint:: Look for the function **ShapesTransformationPlugin_createOutputSample()**, called from **ShapesTransformation_transform()** and use **DDS_DynamicData_get_long()** before **DDS_DynamicData_set_long()**. #. Recompile the transformation (the new shared library will be copied automatically) and run |RS| as before. .. _section-Tutorials-Example6: Example: Using Remote Administration ==================================== In this example, we will configure |RS| remotely. We won't see data being routed until we remotely enable an |ATR| after the application is started. Then we will change a QoS value and see that it takes effect on the fly. #. Start |SHAPESDEMO|. We'll call this the Publishing Demo. It uses domain ID 0. #. In the Publishing Demo, publish some Squares, Circles, and Triangles. #. Start |RS| by entering the following in a command shell: .. code-block:: console cd bin/rtiroutingservice -cfgFile /routing_service/shapes/administration.xml \ -cfgName example -appName MyRoutingService #. Start a second copy of |SHAPESDEMO|. We'll call this the Subscribing Demo. Then: * Open its Configuration dialog (under Controls). * Press **Stop**. * Change the domain ID to 1. * Press **Start**. #. In the Subscribing Demo, subscribe to Squares, Circles, and Triangles. Notice that no data is routed to domain 1. #. On a different or the same machine, start the |RS| remote shell: .. code-block:: console cd bin/rtirssh -domainId 0 .. note:: We use domain 0 in the shell because |RS| is configured in administration.xml to receive remote commands on that domain. You could have started |RS| with the **-remoteAdministrationDomainId** command-line option and then used domain **X** for the shell. #. In the shell, enter the following command: .. code-block:: console enable MyRoutingService RemoteConfigExample::Session::Shapes Notice that the shapes are now received on domain 1. The above command consists of two parts: the name of the |RS|, which you gave when you launched the application with the option **-appName**, and the name of the entity you wanted to enable. That name is formed by appending its parent entities' names starting from the domain route as defined in the configuration file administration.xml. You could have run |RS| without **-appName**. Then the name would be the one provided with **-cfgName** (“example”). You could also have used **-identifyExecution** to generate the name based on the host and application ID. In this case, you would have used this automatic name in the shell. #. Examine the file **/routing_service/shapes/time_filter_qos.xml** on the |RS| machine. It contains an XML snippet that defines a QoS value for an auto topic route's DataReader. Execute the following command in the shell: .. code-block:: console update MyRoutingService RemoteConfigExample::Session::Shapes \ /routing_service/shapes/time_filter_qos.xml Notice that the receiving application only gets shapes every 2 seconds. The |ATR| has been configured to read (and forward) samples with a minimum separation of 2 seconds. |RS| can be configured remotely using files located on the remote machine or the shell machine. In the next step you will edit the configuration files on both machines. Then you will see how to specify which of the two configuration files you want to use. .. note:: If you are running the shell and |RS| on the same machine, skip steps 9 and 10. #. Edit the XML configuration files on both machines: - In **/routing_service/shapes/time_filter_qos.xml** on the service machine, change the minimum separation to 0 seconds. - In **/routing_service/shapes/time_filter_qos.xml** on the shell machine, change the minimum separation to 5 seconds. #. Run the following commands in the shell: - Enter the following command. Notice the use of **remote** at the end—this means you want to use the XML file on the service machine (the remote machine, which is the default if nothing is specified). .. code-block:: console update MyRoutingService RemoteConfigExample::Session::Shapes \ /routing_service/shapes/time_filter_qos.xml remote .. note:: The path to the XML file in this example is relative to the working directory from which you run |RS|. Since no time filter applies, the shapes are received as they are published. - Enter the following command. This time use **local** at the end—this means you want to use the XML file on the shell machine (the local machine). .. code-block:: console update MyRoutingService RemoteConfigExample::Session::Shapes \ /routing_service/shapes/time_filter_qos.xml local .. note:: The path to the XML file in this example is relative to the working directory from which you run the |RS| shell. You will see that now the shapes are only received every 5 seconds. - Enter the following command. Once again, we use *remote* at the end to switch back to the XML file on the remote machine. .. code-block:: console update MyRoutingService RemoteConfigExample::Session::Shapes \ /routing_service/shapes/time_filter_qos.xml remote Shapes are once again received as they are published #. Disable the |ATR| again by entering: .. code-block:: console disable MyRoutingService RemoteConfigExample::Session::Shapes The shapes are no longer received on Domain 1. .. note:: At this point, you could still update the |ATR|’s configuration. You could also change immutable QoS values, since the |DW| and |DR| haven’t been created yet. These changes would take effect the next time you called enable. #. Run these commands in the shell and see what happens after each one: .. code-block:: console enable MyRoutingService RemoteConfigExample::Session::SquaresToCircles disable MyRoutingService RemoteConfigExample::Session::SquaresToCircles enable MyRoutingService RemoteConfigExample::Session::SquaresToTriangles These commands change the output topic that is published after receiving the input Square topic. As you can see, you can use the shell to switch |TRs| after |RS| has been started. #. Perform a remote shutdown of the service. Run the following command: .. code-block:: console shutdown MyRoutingService You should receive a reply indicating that the shutdown sequence has been initiated. Verify in the terminal in which |RS| was running that the process is exiting or has already exited. #. Stop the shell by running this command in the shell: .. code-block:: console exit .. _section-Tutorials-Example7: Example: Monitoring =================== You can publish status information with |RS|. The monitoring configuration is quite flexible and allows you to select the entities that you want to monitor and how often they should publish their status. #. Start |SHAPESDEMO|. We'll call this the Publishing Demo. It uses domain ID 0. #. In the Publishing Demo, publish two Squares, two Circles and two Triangles. #. Start a second copy of |SHAPESDEMO|. We'll call this the Subscribing Demo. Then: * Open its Configuration dialog (under Controls). * Press **Stop**. * Change the domain ID to 1. * Press **Start**. #. In the Subscribing Demo, subscribe to Squares, Circles, and Triangles. At this point you will not see any shapes moving in the Subscribing Demo. It isn’t receiving shapes from the Publishing Demo because they use different domain IDs. #. Start |RS| by entering the following in a command shell: .. code-block:: console cd bin/rtiroutingservice -cfgFile /routing_service/shapes/monitoring.xml \ -cfgName example -appName MyRoutingService This configuration file routes Squares and Circles using two different |TRs|. #. Now you can subscribe to the monitoring topics (see :ref:`section-Monitoring`). You can do it in your own application, or by using *RTI Admin Console* or |RTISPY|. Enter the following in a terminal: .. code-block:: console cd bin/rtiddsspy -domainId 2 –printSample .. note:: We use domain 2 because |RS| is configured in **monitoring.xml** to publish status information on that domain. You could have started |RS| with the **-remoteMonitoringDomainId X** command-line option and then used domain **X** for |RTISPY|. #. Depending on the publication period of the entity in the XML file we used, you will receive status samples at different rates. In the output from |RTISPY|, check the statistics about the two topic routes we are using. We will focus on the input samples per second. The number of samples per second in our case is 32. That value depends on the publication rate of |SHAPESDEMO| configurable with the option **-pubInterval **. #. Create two additional Square publishers in the Publishing Demo (domain 0). #. Check |RTISPY| again for new status information. In the |TR| for Squares, we are receiving double the amount of data. #. Look at the status of the |DR| in the output from |RTISPY|. It contains an aggregation of the two contained |TRs|, giving us a mean of nearly 48 samples per second. #. We can update the monitoring configuration at run time using the remote administration feature. On a different or the same machine, start the |RS| remote shell: .. code-block:: console cd bin/rtirssh -domainId 0 .. note:: We use domain 0 in the shell because |RS| is configured in administration.xml to receive remote commands on that domain. You could have started |RS| with the **-remoteAdministrationDomainId** command-line option and then used domain **X** for the shell. #. We are receiving the status of the |TR| Circles every five seconds. To receive it more often, use the following command: .. code-block:: console update MyRoutingService DomainRoute::Session::Circles \ topic_route.entity_monitoring.status_publication_period.sec=2 #. In some cases, you might want to know only about one specific |TR|. If you only want to know about the topic route Circles but not Squares, you can disable monitoring for Squares: .. code-block:: console update MyRoutingService DomainRoute::Session::Squares \ topic_route.entity_monitoring.enabled=false #. To enable it again, enter: .. code-block:: console update MyRoutingService DomainRoute::Session::Squares \ topic_route.entity_monitoring.enabled=true #. If you are no longer interested in monitoring this service, you can completely disable it with the following command: .. code-block:: console update MyRoutingService routing_service.monitoring.enabled=false Now you won’t receive any more status samples. #. You can enable it again any time by entering: .. code-block:: console update MyRoutingService routing_service.monitoring.enabled=true #. Stop |RTISPY| by pressing **Ctrl-c**. #. Stop the shell: .. code-block:: console exit #. Stop Routing Service by pressing **Ctrl-c**. .. _section-Tutorials-TcpExample: Example: WAN Connectivity using the TCP transport ================================================= This example shows how to use |RS| to bridge data between different LANs over the WAN using TCP. See :ref:`section-routingData-TraversingWan` for a guided and detailed explanation to understand the configuration for this example. :numref:`FigureRouterExampleWanTCP` shows the example scenario. There are two instances of |RS| acting as WAN gateways. ``GatewaySiteA`` is the |RS| that connects the databus for domain 0 in the ``site A`` LAN. Similarly, ``GatewaySiteB`` is the |RS| that connects the databus for domain 2 in the ``site B`` LAN. Note that ``GatewaySiteA`` runs in a host behind a NAT/Firewall, with a public address and forwarded public port to that host. Hence this information is required in the TCP configuration of ``GatewaySiteA``. .. figure:: static/RouterExampleWanTCP.svg :figwidth: 90 % :name: FigureRouterExampleWanTCP2 :align: center Example using the TCP transport to traverse WAN This example uses XML configuration variables in order to reuse the same participant QoS and service configuration. You will need to set to appropriate values (if different than default) when you run |RS| for each site. For the steps shown in this example, the following values are chosen: .. list-table:: Values for configuration variables in this example :name: TableExampleWanTCPConfVariables :widths: 20 20 60 :header-rows: 1 :class: longtable * - Variable - ``GatewaySiteA`` - ``GatewaySiteB`` * - PUBLIC_ADDRESS - 10.10.1.140 - 10.10.1.150 * - REMOTE_RS_PEER - tcpv4_wan://10.10.1.150:8400 - tcpv4_wan://10.10.1.140:7400 * - BIND_PORT - 7400 - 8400 * - LAN_DOMAIN_ID - 0 - 2 The configuration for both instances of |RS| is included in :download:`rti_rs_example_tcp_wan.xml <../example/shapes/rti_rs_example_tcp_wan.xml>`. Place it into the working directory you will run the |RS|. - On ``GatewaySiteA`` host (behind a NAT/firewall with a public IP): #. In the ``Site A`` network, configure the firewall to forward the TCP ports used by |RS|. In this example, we will use port 7400 (for both private and public). You do not need to configure your firewall for every single |CONNEXT| application in your LAN; doing it just once for |RS| will allow other applications to communicate through the firewall. .. note:: You can use tools like Netcat or Ncat, depending on your platform, to verify that the port forwarding has been enabled before moving on with the next steps. For instance, you can run a simple client/server test between the machines running ``GatewaySiteA`` (server) and ``GatewaySiteB`` (client). #. Start |RS| with the ``GatewaySiteA`` configuration To run with the default values for the XML variables: .. code-block:: console cd bin/rtiroutingservice -cfgFile rti_rs_example_tcp_wan.xml \ -cfgName WanGateway \ -appName GatewaySiteA You can set the values for the XML configuration variables in the environment: .. tabs:: .. group-tab:: Linux/macOS .. code-block:: console $ export PUBLIC_ADDRESS=: $ export BIND_PORT= $ export REMOTE_RS_PEER= $ export LAN_DOMAIN_ID= .. group-tab:: Windows .. code-block:: doscon > set PUBLIC_ADDRESS=: > set BIND_PORT= > set REMOTE_RS_PEER= > set LAN_DOMAIN_ID= Now run the |RS| instance: .. code-block:: console cd bin/rtiroutingservice -cfgFile rti_rs_example_tcp_wan.xml \ -cfgName WanGateway \ -appName GatewaySiteA For example: .. code-block:: console cd export PUBLIC_ADDRESS=10.10.1.140:7400 export BIND_PORT=7400 export REMOTE_RS_PEER=tcpv4_wan://10.10.1.150:8400 export LAN_DOMAIN_ID=0 bin/rtiroutingservice -cfgFile rti_rs_example_tcp_wan.xml \ -cfgName WanGateway \ -appName GatewaySiteA #. On any computer in Site A LAN, start |SHAPESDEMO| on domain 0 and publish Squares. If the computer running |SHAPESDEMO| is different than the host running ``GatewaySiteA``, you may need to set the initial peers to the address of that host. You can do this by setting the ``NDDS_DISCOVERY_PEERS`` environment variable before starting |SHAPESDEMO|. - On the Second Peer (a machine in any other LAN): #. In the ``Site A`` network, configure the firewall to forward the TCP ports used by |RS|. In this example, we will use port 7400 (for both private and public). You do not need to configure your firewall for every single |CONNEXT| application in your LAN; doing it just once for |RS| will allow other applications to communicate through the firewall. #. Start |RS| with the ``GatewaySiteB`` configuration To run with the default values for the XML variables: .. code-block:: console cd bin/rtiroutingservice -cfgFile rti_rs_example_tcp_wan.xml \ -cfgName WanGateway \ -appName GatewaySiteB You can set the values for the XML configuration variables in the environment: .. tabs:: .. group-tab:: Linux/macOS .. code-block:: console $ export PUBLIC_ADDRESS=: $ export BIND_PORT= $ export REMOTE_RS_PEER= $ export LAN_DOMAIN_ID= .. group-tab:: Windows .. code-block:: doscon > set PUBLIC_ADDRESS=: > set BIND_PORT= > set REMOTE_RS_PEER= > set LAN_DOMAIN_ID= Now run the |RS| instance: .. code-block:: console cd bin/rtiroutingservice -cfgFile rti_rs_example_tcp_wan.xml \ -cfgName WanGateway \ -appName GatewaySiteB For example: .. code-block:: console cd export PUBLIC_ADDRESS=10.10.1.150:8400 export BIND_PORT=8400 export REMOTE_RS_PEER=tcpv4_wan://10.10.1.140:7400 export LAN_DOMAIN_ID=2 bin/rtiroutingservice -cfgFile rti_rs_example_tcp_wan.xml \ -cfgName WanGateway \ -appName GatewaySiteB #. On any computer in Site B LAN, start |SHAPESDEMO| on domain 2 and subscribe to Squares. If the computer running |SHAPESDEMO| is different than the host running ``GatewaySiteB``, you may need to set the initial peers to the address of that host. You can do this by setting the ``NDDS_DISCOVERY_PEERS`` environment variable before starting |SHAPESDEMO|. Important Considerations ------------------------ - **Using Two Computers in the Same LAN** If both machines are in the same LAN, run both |RS| with the configuration file **tcp_transport_lan.xml**. You will also need to set the peer prefix to **tcpv4_lan://** when setting the discovery peer in the ``RS_REMOTE_PEER`` configuration variable. For example, suppose the first peer is 192.168.1.3, the second peer is 192.168.1.4, and you want to use port 7400. On the first peer set ``NDDS_DISCOVERY_PEERS`` to **tcpv4_lan:// 192.168.1.4:7400** and on the second peer set it to **tcpv4_lan://192.168.1.3:7400**. You don’t need to specify an IP address in the configuration file. - **Using a Secure Connection over WAN** To run the example using a secure connection between the two |RS| instances, use the configuration file **tcp_transport_tls.xml**. You will also need to set the peer prefix to **tlsv4_wan://** when setting the discovery peer in the ``RS_REMOTE_PEER`` configuration variable. The **tcp_transport_tls.xml** file is based on **tcp_transport.xml** and uses a WAN configuration to establish communication. Because TLS is enabled, you must ensure that the **RTI TLS Support** and OpenSSL libraries are present in your library path before starting the applications. .. note:: To run this example, you need the *RTI TCP Transport*, which is shipped with *RTI Connext DDS*. Additionally, you will need to install the optional packages :link_tls_support_install:`RTI TLS support and OpenSSL <>`. - **Using a Secure Connection over LAN** Similar to the previous point, but instead you will use the file **tcp_transport_tls_lan.xml** and prefix **tlsv4_lan://**. .. _section-Tutorials-ExampleFileAdapter: Example: Using a File Adapter ============================= The previous examples showed how to use |RS| with |CONNEXT|. In this one you will learn how to use |RTI_RS| *Adapter SDK* to create an adapter that writes and reads data from files. |RS| allows you to bridge data from different data domains with a pluggable adapter interface. You can find the full example in the :link_community_examples_s:`RTI Community Examples Repository `. To learn how to implement your own adapter, you can follow this example and the explanations from :ref:`section-dataIntegration-FileBaseDomain`. .. _section-Tutorials-ExampleShapesProcessor: Example: Using a Shapes Processor ================================= This example shows how to implement a custom |PROCESSOR| plug-in, build it into a shared library and load it with |RS|. This example illustrates the realization of two common enterprise patterns: aggregation and splitting. There is a single plug-in implementation, *ShapesProcessor* that is a factory of two types of |PROCESSOR|, one for each pattern implementation: - *ShapesAggregator*: |PROCESSOR| implementation that performs the aggregation of two *ShapeType* objects into a single *ShapeType* object. - *ShapesSplitter*: |PROCESSOR| implementation that performs the separation of a single *ShapeType* object into two *ShapeType* objects. In the example, these processors are instantiated as part of a *TopicRoute*, in which all its inputs and outputs represent instantiations of the *Connext DDS Adapter StreamReader* and *StreamWriter*, respectively. You can find the full example in the :link_community_examples_router_shapes_processor:`RTI Community Examples Repository <>`.