13. Tutorials

This chapter describes several examples, all of which use RTI Shapes Demo to publish and subscribe to topics which are colored moving shapes. Shapes Demo is installed automatically with RTI Connext DDS 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 Paths Mentioned in Documentation to understand where to find the examples (referred to as <path to examples>).

• 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 Shapes Demo and Routing Service 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 Routing Service on Host 1 and Shapes Demo on Host 2 and Host 3. In this case, the environment variable would be set as follows:

  Host 1

  Linux/macOS

  Windows

  $ export NDDS_DISCOVERY_PEERS=<host2>,<host3>
  

  > set NDDS_DISCOVERY_PEERS=<host2>,<host3>
  

  Host 2

  Linux/macOS

  Windows

  $ export NDDS_DISCOVERY_PEERS=<host1>
  

  > set NDDS_DISCOVERY_PEERS=<host1>
  

  Host 3

  Linux/macOS

  Windows

  $ export NDDS_DISCOVERY_PEERS=<host1>
  

  > set NDDS_DISCOVERY_PEERS=<host1>
  

13.1. Starting Shapes Demo

You can start Shapes Demo from the Learn tab in RTI Launcher.

Or from a command shell:

Linux/macOS

Windows

$ NDDSHOME/bin/rtishapesdemo

> %NDDSHOME%\bin\rtishapesdemo.bat

NDDSHOME is described in Paths Mentioned in Documentation.

13.2. Example: Routing a single specific Topic

1. Start Shapes Demo on domain 0 and publish squares. We’ll call this the Publishing Demo.

2. Start another instance of Shapes Demo 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 Routing Service yet.

3. Get the example configuration rti_rs_example_square_topic.xml. and place it into your working directory.

4. Run Routing Service by entering the following in a command shell:

   $ cd <NDDSHOME>
   $ bin/rtiroutingservice \
       -cfgFile rti_rs_example_square_topic.xml \
       -cfgName SquareRouter \
       -verbosity LOCAL
   

   Now you should see all the shapes in the Subscribing Demo.

5. Stop Routing Service by pressing Ctrl-c

13.3. Example: Routing All Data from One Domain to Another

This example uses the default configuration file 1 for Routing Service, which routes all data published on domain 0 to subscribers on domain 1.

1. Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.

2. Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:

   • Open its Configuration dialog (under Controls).

   • Press Stop.

   • Change the domain ID to 1.

   • Press Start.

3. In the Publishing Demo, publish some Squares, Circles, and Triangles.

4. 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 Routing Service yet, data from domain 0 isn’t routed to domain 1.

5. Start Routing Service by entering the following in a command shell:

   cd <NDDSHOME>
   bin/rtiroutingservice -cfgName default
   

   Now you should see all the shapes in the Subscribing Demo.

6. Stop Routing Service by pressing Ctrl-c.

   You should see that the Subscribing Demo stops receiving shapes.

Additionally, you can start Routing Service (Step 5) with the following parameters:

• -verbosity 3, to see messages from Routing Service 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 Shapes Demo 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.

1

<NDDSHOME>/resource/xml/RTI_ROUTING_SERVICE.xml

13.4. Example: Changing Data to a Different Topic of Same Type

In this example, Routing Service receives samples of topic Square and republishes them as samples of topic Circle.

1. Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.

2. Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:

   • Open its Configuration dialog (under Controls).

   • Press Stop.

   • Change the domain ID to 1.

   • Press Start.

3. In the Publishing Demo, publish some Squares, Circles, and Triangles.

4. 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.

5. Start Routing Service by entering the following in a command shell:

   cd <NDDSHOME>
   bin/rtiroutingservice
   -cfgFile <path to examples>/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.

6. Stop Routing Service by pressing Ctrl-c.

7. 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 Shapes Demo windows.

13.5. 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 use a Transformation to see how to change the value of some fields in the samples and republish them.

Note

Routing Service provides a transformation that is able to map fields of the input type to fields of the output type using the property tag inside the transformation to provide this mapping. The <name> tag indicates the name of the field in the output type; the <value> tag indicates the name of the field in the input type. Use dot notation for nested fields (e.g., position.x).

Important: The assign transformation only supports the assignment of primitive fields (including strings) that are not part of arrays or sequences. So, for example, x[0] is not supported.

1. Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.

2. Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:

   • Open its Configuration dialog (under Controls).

   • Press Stop.

   • Change the domain ID to 1.

   • Press Start.

3. In the Publishing Demo, publish some Squares.

4. Start Routing Service by entering the following in a command shell:

   cd <NDDSHOME>
   bin/rtiroutingservice
   -cfgFile <path to examples>/routing_service/shapes/topic_bridge_w_transf1.xml \
   -cfgName example
   

5. In the Subscribing Demo, subscribe to Squares.

   Notice that the (x,y) coordinates of the shapes are inverted form what appears in the Publishing Demo.

6. Stop Routing Service by pressing Ctrl-c.

7. Try changing the transformation to assign the output shapesize to the input x.

13.6. 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 rtiddsspy to verify the result. rtiddsspy is a utility provided with Connext DDS; it monitors publications on any DDS domain.

Note

Routing Service provides a transformation that is able to map fields of the input type to fields of the output type using the property tag inside the transformation to provide this mapping. The <name> tag indicates the name of the field in the output type; the <value> tag indicates the name of the field in the input type. Use dot notation for nested fields (e.g., position.x).

Important: The assign transformation only supports the assignment of primitive fields (including strings) that are not part of arrays or sequences. So, for example, x[0] is not supported.

1. Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.

2. In the Publishing Demo, publish some Squares.

3. Start Routing Service by entering the following in a command shell:

   cd <NDDSHOME>
   bin/rtiroutingservice
   -cfgFile <path to examples>/routing_service/shapes/topic_bridge_w_transf2.xml \
   -cfgName example
   

4. We will use the rtiddsspy utility to verify the transformation of the data topic and type. Run these commands:

   cd <NDDSHOME>
   bin/rtiddsspy -domainId 0 -printSample
   bin/rtiddsspy -domainId 1 -printSample
   

   You will notice that the publishing samples received by rtiddsspy for domain 0 are of type ShapeType and topic Square. The subscribing samples received by rtiddsspy for domain 1 are of type Point and topic Position. Notice that the two data structures are different.

5. Stop Routing Service by pressing Ctrl-c.

13.7. Example: Transforming the Data with a Custom Transformation

Now we will use our own transformation between shapes. Routing Service 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 DDS libraries installed.

Note

This example assumes your working directory is <path to examples>/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.

1. Compile the transformation in <path to examples>/routing_service/shapes/transformation/[make or windows]:

   • On Linux/macOS systems:

     • Set the environment variable NDDSHOME (see Paths Mentioned in Documentation). An easy way to do this is to run rtisetenv: $ source <installdir>/resource/scripts/rtisetenv_<architecture>.bash. (For more information about rtisetenv, see Set Up Environment Variables (rtisetenv), in the RTI Connext DDS Getting Started Guide.)

     • Enter:

     cd <path to examples>/routing_service/shapes/transformation/make
     make -f Makefile.<architecture>
     

   • On Windows systems:

     • Set the environment variable NDDSHOME (see Paths Mentioned in Documentation). An easy way to do this is to run rtisetenv: > <installdir>\resource\scripts\rtisetenv_<architecture>.bat. (For more information about rtisetenv, see Set Up Environment Variables (rtisetenv), in the RTI Connext DDS Getting Started Guide.)

     • Open the Visual Studio solution under <path to examples>\routing_service\shapes\transformation\windows.

     • Select the Release DLL build mode and build the solution.

2. Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.

3. In the Publishing Demo, publish some Squares.

4. Start Routing Service by entering the following in a command shell:

   cd <NDDSHOME>
   bin/rtiroutingservice
   -cfgFile <path to examples>/routing_service/shapes/topic_bridge_w_custom_transf.xml \
   -cfgName example
   

5. Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:

   • Open its Configuration dialog (under Controls).

   • Press Stop.

   • Change the domain ID to 1.

   • Press Start.

6. In the Subscribing Demo, subscribe to Squares.

   Notice that squares on domain 1 have only two possible values for x.

7. Stop Routing Service by pressing Ctrl-c.

8. Change the fixed ‘x’ values for the Squares in the configuration file and restart Routing Service.

9. Stop Routing Service by pressing Ctrl-c.

10. 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().

11. Recompile the transformation (the new shared library will be copied automatically) and run Routing Service as before.

13.8. Example: Using Remote Administration

In this example, we will configure Routing Service remotely. We won’t see data being routed until we remotely enable an AutoTopicRoute after the application is started. Then we will change a QoS value and see that it takes effect on the fly.

1. Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.

2. In the Publishing Demo, publish some Squares, Circles, and Triangles.

3. Start Routing Service by entering the following in a command shell:

   cd <NDDSHOME>
   bin/rtiroutingservice
   -cfgFile <path to examples>/routing_service/shapes/administration.xml \
   -cfgName example -appName MyRoutingService
   

4. Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:

   • Open its Configuration dialog (under Controls).

   • Press Stop.

   • Change the domain ID to 1.

   • Press Start.

5. In the Subscribing Demo, subscribe to Squares, Circles, and Triangles.

   Notice that no data is routed to domain 1.

6. On a different or the same machine, start the Routing Service remote shell:

   cd <NDDSHOME>
   bin/rtirssh -domainId 0
   

   Note

   We use domain 0 in the shell because Routing Service is configured in administration.xml to receive remote commands on that domain. You could have started Routing Service with the -remoteAdministrationDomainId command-line option and then used domain X for the shell.

7. In the shell, enter the following command:

   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 Routing Service, 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 Routing Service 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.

8. Examine the file <path to examples>/routing_service/shapes/time_filter_qos.xml on the Routing Service 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:

   update MyRoutingService RemoteConfigExample::Session::Shapes \
           <path to examples>/routing_service/shapes/time_filter_qos.xml
   

   Notice that the receiving application only gets shapes every 2 seconds. The AutoTopicRoute has been configured to read (and forward) samples with a minimum separation of 2 seconds.

   Routing Service 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 Routing Service on the same machine, skip steps 9 and 10.

9. Edit the XML configuration files on both machines:

   • In <path to examples>/routing_service/shapes/time_filter_qos.xml on the service machine, change the minimum separation to 0 seconds.

   • In <path to examples>/routing_service/shapes/time_filter_qos.xml on the shell machine, change the minimum separation to 5 seconds.

10. 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).

      update MyRoutingService RemoteConfigExample::Session::Shapes \
          <path to examples>/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 Routing Service.

      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).

      update MyRoutingService RemoteConfigExample::Session::Shapes \
          <path to examples>/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 Routing Service 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.

      update MyRoutingService RemoteConfigExample::Session::Shapes \
          <path to examples>/routing_service/shapes/time_filter_qos.xml remote
      

      Shapes are once again received as they are published

11. Disable the AutoTopicRoute again by entering:

    disable MyRoutingService RemoteConfigExample::Session::Shapes
    

    The shapes are no longer received on Domain 1.

    Note

    At this point, you could still update the AutoTopicRoute’s configuration. You could also change immutable QoS values, since the DataWriter and DataReader haven’t been created yet. These changes would take effect the next time you called enable.

12. Run these commands in the shell and see what happens after each one:

    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 TopicRoutes after Routing Service has been started.

13. Perform a remote shutdown of the service. Run the following command:

    shutdown MyRoutingService
    

    You should receive a reply indicating that the shutdown sequence has been initiated. Verify in the terminal in which Routing Service was running that the process is exiting or has already exited.

14. Stop the shell by running this command in the shell:

    exit
    

13.9. Example: Monitoring

You can publish status information with Routing Service. 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.

1. Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.

2. In the Publishing Demo, publish two Squares, two Circles and two Triangles.

3. Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:

   • Open its Configuration dialog (under Controls).

   • Press Stop.

   • Change the domain ID to 1.

   • Press Start.

4. 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.

5. Start Routing Service by entering the following in a command shell:

   cd <NDDSHOME>
   bin/rtiroutingservice
   -cfgFile <path to examples>/routing_service/shapes/monitoring.xml \
   -cfgName example -appName MyRoutingService
   

   This configuration file routes Squares and Circles using two different TopicRoutes.

6. Now you can subscribe to the monitoring topics (see Monitoring). You can do it in your own application, or by using RTI Admin Console or rtiddsspy. Enter the following in a terminal:

   cd <NDDSHOME>
   bin/rtiddsspy -domainId 2 –printSample
   

   Note

   We use domain 2 because Routing Service is configured in monitoring.xml to publish status information on that domain. You could have started Routing Service with the -remoteMonitoringDomainId X command-line option and then used domain X for rtiddsspy.

7. 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 rtiddsspy, 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 Shapes Demo configurable with the option -pubInterval <milliseconds between writes>.

8. Create two additional Square publishers in the Publishing Demo (domain 0).

9. Check rtiddsspy again for new status information.

   In the TopicRoute for Squares, we are receiving double the amount of data.

10. Look at the status of the DataReader in the output from rtiddsspy.

    It contains an aggregation of the two contained TopicRoutes, giving us a mean of nearly 48 samples per second.

11. We can update the monitoring configuration at run time using the remote administration feature.

    On a different or the same machine, start the Routing Service remote shell:

    cd <NDDSHOME>
    bin/rtirssh -domainId 0
    

    Note

    We use domain 0 in the shell because Routing Service is configured in administration.xml to receive remote commands on that domain. You could have started Routing Service with the -remoteAdministrationDomainId command-line option and then used domain X for the shell.

12. We are receiving the status of the TopicRoute Circles every five seconds. To receive it more often, use the following command:

    update MyRoutingService DomainRoute::Session::Circles \
            topic_route.entity_monitoring.status_publication_period.sec=2
    

13. In some cases, you might want to know only about one specific TopicRoute. If you only want to know about the topic route Circles but not Squares, you can disable monitoring for Squares:

    update MyRoutingService DomainRoute::Session::Squares \
        topic_route.entity_monitoring.enabled=false
    

14. To enable it again, enter:

    update MyRoutingService DomainRoute::Session::Squares \
        topic_route.entity_monitoring.enabled=true
    

15. If you are no longer interested in monitoring this service, you can completely disable it with the following command:

    update MyRoutingService routing_service.monitoring.enabled=false
    

    Now you won’t receive any more status samples.

16. You can enable it again any time by entering:

    update MyRoutingService routing_service.monitoring.enabled=true
    

17. Stop rtiddsspy by pressing Ctrl-c.

18. Stop the shell:

    exit
    

19. Stop Routing Service by pressing Ctrl-c.

13.10. Example: WAN Connectivity using the TCP transport

This example shows how to use Routing Service to bridge data between different LANs over the WAN using TCP. See Traversing Wide Area Networks for a guided and detailed explanation to understand the configuration for this example.

Figure 2.10 shows the example scenario. There are two instances of Routing Service acting as WAN gateways. GatewaySiteA is the Routing Service that connects the databus for domain 0 in the site A LAN. Similarly, GatewaySiteB is the Routing Service 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 13.1 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 Routing Service for each site. For the steps shown in this example, the following values are chosen:

Table 13.1 Values for configuration variables in this example

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 Routing Service is included in rti_rs_example_tcp_wan.xml. Place it into the working directory where you will run the Routing Service.

• On GatewaySiteA host (behind a NAT/firewall with a public IP):

  1. In the Site A network, configure the firewall to forward the TCP ports used by Routing Service.

     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 DDS application in your LAN; doing it just once for Routing Service 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).

  1. Start Routing Service with the GatewaySiteA configuration

     To run with the default values for the XML variables:

     cd <NDDSHOME>
     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:

     Linux/macOS

     Windows

     $ export PUBLIC_ADDRESS=<Host Site A public IP>:<Host Site A public Port>
     $ export BIND_PORT=<RS TCP bind port>
     $ export REMOTE_RS_PEER=<discovery peer for GatewaySiteB>
     $ export LAN_DOMAIN_ID=<ID for the LAN domain in site A>
     

     > set PUBLIC_ADDRESS=<Host Site A public IP>:<Host Site A public Port>
     > set BIND_PORT=<RS TCP bind port>
     > set REMOTE_RS_PEER=<discovery peer for GatewaySiteB>
     > set LAN_DOMAIN_ID=<ID for the LAN domain in site A>
     

     Now run the Routing Service instance:

     cd <NDDSHOME>
     bin/rtiroutingservice
             -cfgFile rti_rs_example_tcp_wan.xml \
             -cfgName WanGateway \
             -appName GatewaySiteA
     

     For example:

     cd <NDDSHOME>
     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
     

  2. On any computer in Site A LAN, start Shapes Demo on domain 0 and publish Squares.

     If the computer running Shapes Demo 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 Shapes Demo.

• On the Second Peer (a machine in any other LAN):

  1. In the Site A network, configure the firewall to forward the TCP ports used by Routing Service.

     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 DDS application in your LAN; doing it just once for Routing Service will allow other applications to communicate through the firewall.

  2. Start Routing Service with the GatewaySiteB configuration

     To run with the default values for the XML variables:

     cd <NDDSHOME>
     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:

     Linux/macOS

     Windows

     $ export PUBLIC_ADDRESS=<Host Site B public IP>:<Host Site B public Port>
     $ export BIND_PORT=<RS TCP bind port>
     $ export REMOTE_RS_PEER=<discovery peer for GatewaySiteA>
     $ export LAN_DOMAIN_ID=<ID for the LAN domain in site B>
     

     > set PUBLIC_ADDRESS=<Host Site B public IP>:<Host Site B public Port>
     > set BIND_PORT=<RS TCP bind port>
     > set REMOTE_RS_PEER=<discovery peer for GatewaySiteA>
     > set LAN_DOMAIN_ID=<ID for the LAN domain in site B>
     

     Now run the Routing Service instance:

     cd <NDDSHOME>
     bin/rtiroutingservice
             -cfgFile rti_rs_example_tcp_wan.xml \
             -cfgName WanGateway \
             -appName GatewaySiteB
     

     For example:

     cd <NDDSHOME>
     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
     

  3. On any computer in Site B LAN, start Shapes Demo on domain 2 and subscribe to Squares.

     If the computer running Shapes Demo 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 Shapes Demo.

13.10.1. Important Considerations

• Using Two Computers in the Same LAN

  If both machines are in the same LAN, run both Routing Service 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 Routing Service 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 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://.

13.11. Example: Using a File Adapter

The previous examples showed how to use Routing Service with Connext DDS. In this one you will learn how to use RTI Routing Service Adapter SDK to create an adapter that writes and reads data from files. Routing Service allows you to bridge data from different data domains with a pluggable adapter interface.

You can find the full example in the RTI Community Examples Repository. To learn how to implement your own adapter, you can follow this example and the explanations from Integrating a File-Based Domain.

13.12. 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 Routing Service.

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 RTI Community Examples Repository.