.. 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. In each example, you can start all the applications on the same computer or on different computers in your network. If you don't have |SHAPESDEMO| installed already, you should download and install it from `RTI’s Downloads page `_ or the `RTI Support Portal `_ (the latter requires an account name and password). If you are not already familiar with how to start |SHAPESDEMO| and change its domain ID, please see the |SHAPESDEMO| *User's Manual* for details. Important Notes: - Please review :numref:`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: Host 1: .. code-block:: bash set NDDS_DISCOVERY_PEERS=, (on Windows systems) export NDDS_DISCOVERY_PEERS=, (on UNIX-based systems) Host 2: .. code-block:: bash set NDDS_DISCOVERY_PEERS= Host 3: .. code-block:: bash export 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: .. code-block:: bash /bin/rtishapesdemo NDDSHOME is described in :numref:`section-Introduction-Paths`. .. _section-Tutorials-Example1: 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:: bash 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. #. Start |RS| by entering the following in a command shell: .. code-block:: bash cd bin/rtiroutingservice -cfgFile /routing_service/shapes/topic_bridge.xml \ -cfgName example #. 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. #. 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:: bash 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, Circles, and Triangles. #. Start |RS| by entering the following in a command shell: .. code-block:: bash 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:: bash 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-Example5: 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 UNIX-based systems: - Set the environment variable NDDSHOME (see :numref:`section-Introduction-Paths`). For details on how to set it, see the *RTI Connext DDS Core Libraries Getting Started Guide*. - Enter: .. code-block:: bash cd /routing_service/shapes/transformation/make gmake -f Makefile. - On Windows systems: - Set the environment variable NDDSHOME (see :numref:`section-Introduction-Paths`). For details on how to set it, see the *RTI Connext DDS Core Libraries 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:: bash 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:: bash 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:: bash 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:: bash 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:: bash 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:: bash 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:: bash 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:: bash 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:: bash 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:: bash 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:: bash 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:: bash 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. #. On a different or the same machine, start the |RS| remote shell: .. code-block:: bash 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. #. Start |RS| by entering the following in a command shell: .. code-block:: bash 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 :numref:`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:: bash 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. In the configuration file, we enabled remote administration on domain 0. On a different or the same machine, start the |RS| remote shell: .. code-block:: bash cd bin/rtirssh -domainId 0 #. We are receiving the status of the |TR| Circles every five seconds. To receive it more often, use the following command: .. code-block:: bash 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:: bash update MyRoutingService DomainRoute::Session::Squares \ topic_route.entity_monitoring.enabled=false #. To enable it again, enter: .. code-block:: bash 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:: bash 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:: bash update MyRoutingService routing_service.monitoring.enabled=true #. Stop |RTISPY| by pressing **Ctrl-c**. #. Stop the shell: .. code-block:: bash exit #. Stop Routing Service by pressing **Ctrl-c**. .. _section-Tutorials-Example8: Example: Using the TCP Transport ================================ This example shows how to use |RS| to bridge data between different LANs over TCP. |RS| will act as the gateway in a LAN with which other |CONNEXT| applications can communicate to send or receive data. :numref:`section-wan` has more information about scenarios and detailed configuration parameters. You will run two copies of |RS|. One copy will run on a machine that is behind a firewall/network router with a public IP (First Peer); the other will run on a machine in another LAN (Second Peer). .. figure:: static/RouterExampleTcp.png :figwidth: 60 % :name: FigureRouterExampleTcp :align: center - On the First Peer (behind a firewall/router with a public IP): #. In the First Peer's network, configure the firewall to forward the TCP ports used by |RS|. In this example, we will use port 7400. 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. #. Include the Second Peer’s public IP address and port in the ``NDDS_DISCOVERY_PEERS`` environment variable. For example, on a UNIX-based system: .. code-block:: bash export NDDS_DISCOVERY_PEERS=tcpv4_wan://: On a Windows system: .. code-block:: bash set NDDS_DISCOVERY_PEERS=tcpv4_wan://: When you configure ``NDDS_DISCOVERY_PEERS``, make sure to use a transport class prefix (tcpv4_wan, udpv4, shmem) for each entry. See :link_discovery_peers_config:`discovery peer configuration <>` for details. #. Set the public IP address and port in the configuration file: - Open the file **/routing_service/shapes/tcp_transport.xml.** - The file contains several configurations. Find the configuration with name "TCP_1". Then find the "public_address" property (dds.transport.TCPv4.tcp1.public_address) within that configuration. - Set the local public IP address and port. For example, to set the address to 10.10.1.150 and port 7400: .. code-block:: xml dds.transport.TCPv4.tcp1.public_address 10.10.1.150:7400 - Save and close the file. #. Start |RS| by entering the following in a command shell: .. code-block:: bash cd bin/rtiroutingservice -cfgFile /routing_service/shapes/tcp_transport.xml \ -cfgName TCP_1 #. On any computer in this LAN, start |SHAPESDEMO| and publish some shapes on domain 0. - On the Second Peer (a machine in any other LAN): #. Include the First Peer’s public IP address and port in the ``NDDS_DISCOVERY_PEERS`` environment variable the same way you did before. #. Set the public IP address and port in the configuration file: - Open the file **/routing_service/shapes/tcp_transport.xml.** - The file contains several configurations. Find the configuration with name "TCP_2". Then find the "public_address" property (dds.transport.TCPv4.tcp1.public_address) within that configuration. - Set the local public IP address and port. For example, to set the address to 10.10.1.10 and port 7400: .. code-block:: xml dds.transport.TCPv4.tcp1.public_address 10.10.1.10:7400 - Save and close the file. #. Start |RS| by entering the following in a command shell: .. code-block:: bash cd bin/rtiroutingservice -cfgFile /routing_service/shapes/tcp_transport.xml \ -cfgName TCP_2 #. On any computer in this LAN, start |SHAPESDEMO| and create subscribers on domain 2. Do not use an already running instance of |SHAPESDEMO|—you need a new one that uses a different domain ID. You should receive what is being published in the server's LAN. - **Notes:** - **Running Shapes Demo on a Different Computer** If the computer running |SHAPESDEMO| is different than the computer running the client |RS|, add the address of the client (IP address or host name) to the |SHAPESDEMO| discovery peers before starting |SHAPESDEMO|. To do so, set the ``NDDS_DISCOVERY_PEERS`` environment variable. - **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** and use **tcpv4_lan://** as the peer prefix in the environment variable ``NDDS_DISCOVERY_PEERS``. At least one of the peer descriptors must contain the port number. 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. - **Running the Example on One Computer** To run the example on the same machine, open the file **/routing_service/ shapes/tcp_transport_lan.xml** and change the property **dds.transport.TCPv4.tcp1.server_bind_port** within **TCP_1** to 7401. Run both |RS| with the modified **tcp_transport_lan.xml** configuration file and use **tcpv4_lan://** as the peer prefix in the environment variable ``NDDS_DISCOVERY_PEERS``. You will also need to specify port 7401 in the **tcpv4_lan** peer in the ``NDDS_DISCOVERY_PEERS`` environment variable of the |RS| in the Second Peer to reflect this port change 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://** in the ``NDDS_DISCOVERY_PEERS`` environment 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-Example9: 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. To learn how to implement your own adapter, you can follow this example and the next examples and inspect the code that is distributed with these adapters. The file adapter can read data from files with a specific format and provide it to |RS|, or receive data from |RS| and write it into files. In this example, we will first write topic data (a colored square and circle) into a file and then use that file to write it back into |CONNEXT|, allowing us to modify the data with a text editor. .. figure:: static/RouterExampleFileAdapter.svg :figwidth: 75 % :name: FigureRouterExampleFigureAdapter :align: center - Compile the Adapter in **adapters/file/src**: - Set NDDSHOME to point to your *RTI Connext DDS* installation. - On UNIX-based systems, enter: .. code-block:: bash cd /routing_service/adapters/file/make gmake -f Makefile. The adapter shared library, **libfileadapter.so**, will be copied to **/routing_service/adapters/file**. - On Windows systems: - Open the Visual Studio solution under **/routing_service/adapters/file/windows**. For example, if you are using Visual Studio 2013, open **fileadapter-vs2013.sln**. - Build the solution. The adapter shared library, **fileadapter.dll**, will be copied to **/routing_service/adapters/file**. - From |CONNEXT| to files: #. Run |SHAPESDEMO| and |RS| as in the previous examples: - Start |SHAPESDEMO| on domain 0 (the default domain). - Start |RS| by entering the following in a command shell: .. code-block:: bash cd bin/rtiroutingservice -cfgFile /routing_service/shapes/file_bridge.xml \ -cfgName dds_to_file #. In |SHAPESDEMO|, publish some Squares. #. Wait a few seconds and then stop |RS| by pressing **Ctrl-c**. #. A file called **MySquare.txt** should have been created in the current directory. Open it with a text editor of your choice. It should contain several lines, each consisting of a list of ``=`` elements. Each line represents a sample (Square) published by |SHAPESDEMO| and written by |RS| and the file adapter. On UNIX-based systems, you can see how new samples are appended to the file by running the following command while |RS| runs: .. code-block:: bash tail - f MySquare.txt - From a file to |CONNEXT|: #. In |SHAPESDEMO|, delete the Square publisher and create a Square subscriber. #. Start |RS| by entering the following in a command shell: .. code-block:: bash cd bin/rtiroutingservice -cfgFile /routing_service/shapes/file_bridge.xml \ -cfgName file_to_dds You should see squares being received by |SHAPESDEMO|. These samples come from what we recorded before. You might have noticed that the rate at which the shape moves is much slower. This is the rate at which the file adapter is providing data to |RS|. To change this rate, open **file_bridge.xml** and look for ```` within ````. In the ````` tag, change the property **ReadPeriod** from 1000 (milliseconds) to 100. #. Stop |RS| and restart it as described in previous steps. The squares should be received and displayed about ten times faster. #. Other properties that you can configure in the file adapter are: In the input, FileName, MaxSampleSize, Loop and SamplesPerRead; in the output, FileName. #. You can also edit the text file and publish the new data. Open **MySquare.txt** and replace all the occurrences of “shapesize=30” with “shapesize=100”. #. Stop |RS| and restart it as described in previous steps. The squares will have the same position and color, but they will be bigger now. - Customize the File Adapter: In the example, the file adapters use a specific format, which you already saw in the file **MySquare.txt**. Now try adapting the example to your own format. The code that reads/writes from the file is in **adapters/file/src/LineConversion.c**. #. Edit the function ``RTI_RoutingServiceFileAdapter_read_sample`` to implement how file data maps into a sample. #. Edit the function ``RTI_RoutingServiceFileAdapter_write_sample`` to implement how a sample is written to a file. .. _section-Tutorials-Example10: 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 <>`.