6. Tutorials

Note

The commands shown in these examples are for the x64Linux3gcc5.4.0 architecture. For simplicity, all the examples assume that all the applications run on the same host machine and the environment variable NDDSHOME is set to point to your RTI Connext DDS installation.

Note

Some of the examples require OpenSSL libraries and you must ensure they are present in your library path before starting the applications. Example commands assume the existence of the environment variable OPENSSLHOMELIB set to the directory that contains the OpenSSL libraries.

If you use the OpenSSL libraries distributed by RTI, the libraries directory will have the following locations:

  • On Unix: <INSTALL DIR>/<architecture>/release/lib
  • On Windows: <INSTALL DIR>\<architecture>\release\bin

6.1. Example: Using a built-in UDP transport

This example illustrates the basic functionality of Cloud Discovery Service. It shows how Connext DDS applications discover each other through an instance of Cloud Discovery Service.

6.1.1. Setup

The first step is to have two Connext DDS applications that can talk to each other. For that, you can use an IDL file of your choice and run rtiddsgen to generate the example. For instance, you can create a file named CDSHelloWorld.idl with the following content:

struct CDSHelloWorld {
    long count;
}

Generate the publisher and subscriber examples by running the following command (you can replace C++03 with any other language of your choice):

$NDDHSOME/bin/rtiddsgen -language C++03  -example x64Linux3gcc5.4.0 \
    -ppDisable CDSHelloWorld.idl

Modify HelloWorld_publisher.cxx to increase the count field each time the sample is written. For instance, you can add the following sentence in the main writing loop:

sample.count(count);

To compile the generated code, run:

make -f makefile_CDSHelloWorld_x64Linux3gcc5.4.0

You should have two executables, CDSHelloWorld_publisher and CDSHelloWorld_subscriber. Now you can run the examples to make sure everything is fine. You need to run the examples from the directory that contains the generated USER_QOS_PROFILES.xml.

From one terminal run:

./objs/x64Linux3gcc5.4.0/CDSHelloWorld_publisher
Writing CDSHelloWorld, count 0
Writing CDSHelloWorld, count 1
...

From a different terminal, run:

./objs/x64Linux3gcc5.4.0/CDSHelloWorld_subscriber
CDSHelloWorld subscriber sleeping for 4 sec...
[count: 3]
CDSHelloWorld subscriber sleeping for 4 sec...
[count: 4]
...

You should see that the subscriber application receives the samples generated by the publisher application. This occurs because by default, DomainParticipants enable multicast. That is, participant announcements are automatically sent to a multicast destination.

6.1.2. Disable Multicast

Stop the applications and disable multicast. For that, you can specify an empty list of initial peers by setting the environment as follows:

export NDDS_DISCOVERY_PEERS=

Now if you run the publisher and subscriber applications again, notice that the subscriber does not receive any samples:

./objs/x64Linux3gcc5.4.0/CDSHelloWorld_subscriber
CDSHelloWorld subscriber sleeping for 4 sec...
CDSHelloWorld subscriber sleeping for 4 sec...
CDSHelloWorld subscriber sleeping for 4 sec...
...

You can stop the applications now.

6.1.3. Cloud Discovery Service in action

To make the applications communicate, we need to run Cloud Discovery Service. From a terminal, run the following command:

$NDDSHOME/bin/rticlouddiscoveryservice

This command will run Cloud Discovery Service with the built-in configuration that listens on port 7400 over UDP transport.

Re-run the publisher and subscriber applications, but this time set the initial peers to talk to Cloud Discovery Service (see Section 3.2.1). For that, you can set the environment from the application terminal as follows:

export NDDS_DISCOVERY_PEERS=[email protected]:7400

Now run the applications and verify that the subscriber receives samples. You can also stop Cloud Discovery Service and see how the applications continue communicating. In addition, you can start more publishers and subscribers, then see how they all discover each other and communicate.

6.2. Example: Using a custom listening port

This example extends Example: Using a built-in UDP transport to run Cloud Discovery Service on a custom listening port over UDP. For that, you can run Cloud Discovery Service as follows:

$NDDSHOME/bin/rticlouddiscoveryservice -transport <port>

where <port> represents the port number you wish. This example will use 10000.

$NDDSHOME/bin/rticlouddiscoveryservice -transport 10000

To see which exact address Cloud Discovery Service is using to listen for participant announcements, run the service with -verbosity 4 and look for the line:

...
[CDS DETECTOR] listening for announcements on:
    udpv4://172.17.0.2:10000
...

Set the initial peers accordingly to indicate where Cloud Discovery Service is listening:

export NDDS_DISCOVERY_PEERS=[email protected]://172.17.0.2:10000

6.3. Example: Using RTI TCP Transport

This example extends Example: Using a built-in UDP transport to use the RTI TCP transport for both discovery and user data. The example shows how to run Cloud Discovery Service using the pre-registered instance of RTI TCP transport.

Note

To run this example, you need RTI TCP Transport, which is shipped with RTI Connext DDS.

6.3.1. Setup

The first step of this example is to configure the publisher and subscriber applications so they communicate over the RTI TCP transport in LAN mode. For that, you can include the following XML code within the <participant_qos> tag of the file USER_QOS_PROFILES.xml generated by rtiddsgen.

<property>
    <value>
        <element>
            <name>dds.transport.load_plugins</name>
            <value>dds.transport.tcp.tcp1</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.library</name>
            <value>nddstransporttcp</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.create_function</name>
            <value>NDDS_Transport_TCPv4_create</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.server_bind_port</name>
            <value>$(BIND_PORT)</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.parent.classid</name>
            <value>NDDS_TRANSPORT_CLASSID_TCPV4_LAN</value>
        </element>
    </value>
</property>

The server bind port property value is obtained from the environment variable $(BIND_PORT). This is a convenience for this example so you can reuse the same file to specify a different port for the publisher and subscriber applications, which is required when running on the same host machine.

Now you can run the applications. You need to run from the directory that contains the generated USER_QOS_PROFILES.xml you just modified.

From the terminal, run:

Listing 6.1 Publisher application
export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0
export BIND_PORT=7401
export NDDS_DISCOVERY_PEERS=tcpv4_lan://localhost:7402

./objs/x64Linux3gcc5.4.0/CDSHelloWorld_publisher
Listing 6.2 Subscriber application
export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0
export BIND_PORT=7402
export NDDS_DISCOVERY_PEERS=tcpv4_lan://localhost:7401

./objs/x64Linux3gcc5.4.0/CDSHelloWorld_subscriber

You should see the subscriber receive samples. This is possible since in the initial peers list, you indicated how the applications can reach each other.

6.3.2. Cloud Discovery Service in action

Now you will use Cloud Discovery Service to provide the discovery for the applications.

From a terminal, run the following command:

export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0
$NDDSHOME/bin/rticlouddiscoveryservice -transport tcpv4:7400

This will run Cloud Discovery Service with the built-in configuration and override the transport selection to use RTI TCP with bind port 7400.

Re-run the publisher and subscriber application, but this time set the initial peers to talk to Cloud Discovery Service (see Section 3.2.1). For that, you can set the environment from the application terminal as follows:

Listing 6.3 Publisher application
 export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0
 export BIND_PORT=7401
 export NDDS_DISCOVERY_PEERS=[email protected]_lan://localhost:7400
Listing 6.4 Subscriber application
 export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0
 export BIND_PORT=7402
 export NDDS_DISCOVERY_PEERS=[email protected]_lan://localhost:7400

Now run the applications and verify that the subscriber receives samples. You can also stop Cloud Discovery Service and see how the applications continue communicating.

6.4. Example: Using RTI TCP Transport with RTI TLS Support

This example extends Example: Using a built-in UDP transport to enable TLS for secure communication. The example shows how to run Cloud Discovery Service using the pre-registered transport instance of the RTI TCP transport with TLS enabled.

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.

6.4.1. Setup

The first step in this example is to configure the publisher and subscriber applications to communicate over the RTI TCP transport in LAN mode with TLS enabled. For that, you can include the following XML code within the <participant_qos> tag of the file USER_QOS_PROFILES.xml generated by rtiddsgen.

<property>
    <value>
        <element>
            <name>dds.transport.load_plugins</name>
            <value>dds.transport.tcp.tcp1</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.library</name>
            <value>nddstransporttcp</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.create_function</name>
            <value>NDDS_Transport_TCPv4_create</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.server_bind_port</name>
            <value>$(BIND_PORT)</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.parent.classid</name>
            <value>NDDS_TRANSPORT_CLASSID_TLSV4_LAN</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.tls.verify.ca_file</name>
            <value>cacert.pem</value>
        </element>
        <element>
            <name>dds.transport.tcp.tcp1.tls.identity.certificate_chain_file</name>
            <value>peer1.pem</value>
        </element>
    </value>
</property>

The server bind port property value is obtained from the environment variable $(BIND_PORT). This is a convenience for this example so you can reuse the same file to specify different ports for the publisher and subscriber applications, which is required when running on the same host machine.

You must also provide certificate files. You can obtain example certificates from the following links:

Now you can run the applications. You need to run from the directory that contains the generated USER_QOS_PROFILES.xml that you just modified and the certificates.

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. See the beginning of this section for a note on how to locate the OpenSSL libraries.

From the terminal run:

Listing 6.5 Publisher application
export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0:$OPENSSLHOMELIB
export BIND_PORT=7401
export NDDS_DISCOVERY_PEERS=tlsv4_lan://localhost:7402

./objs/x64Linux3gcc5.4.0/CDSHelloWorld_publisher
Listing 6.6 Subscriber application
export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0:$OPENSSLHOMELIB
export BIND_PORT=7402
export NDDS_DISCOVERY_PEERS=tlsv4_lan://localhost:7401

./objs/x64Linux3gcc5.4.0/CDSHelloWorld_subscriber

You should see the subscriber receives samples. This is possible since in the initial peers list, you indicated how the applications can reach each other.

6.4.2. Cloud Discovery Service in action

Now you will use Cloud Discovery Service to provide the discovery for the applications. In this case, you need to configure the transport with an instance of the RTI TCP transport with TLS enabled.

The configuration required for this example is shown below:

<?xml version="1.0"?>
<dds  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="http://community.rti.com/schema/latest/rti_cloud_discovery_service.xsd">
            
    <cloud_discovery_service name="ExampleTls">
        <annotation>
            <documentation><![CDATA[ 
                Example that configures the pre-registered instance of the
                RTI TCP transport with TLS enabled.
                ]]>                
            </documentation>
        </annotation>
        <transport>     
            <element>
                <alias>tlsv4_lan</alias>
                <receive_port>7400</receive_port>
                <property>
                    <element>
                        <name>dds.transport.cds.tcp1.tls.verify.ca_file</name>
                        <value>cacert.pem</value>
                    </element>                        
                    <element>
                        <name>dds.transport.cds.tcp1.tls.identity.certificate_chain_file</name>
                        <value>peer1.pem</value>
                    </element>                    
                </property>
            </element>
        </transport>        
    </cloud_discovery_service>
    
</dds>

You can download the configuration file from here: rti_cds_example_tls.xml

From a terminal, run the following command:

export LD_LIBRARY_PATH=$OPENSSLHOMELIB
$NDDSHOME/bin/rticlouddiscoveryservice \
        -cfgFile <working_dir>/rti_cds_example_tls.xml -cfgName ExampleTls

This command will run Cloud Discovery Service with the custom configuration for this example, located under the directory <working_dir>.

Re-run the publisher and subscriber applications, but this time set the initial peers to talk to Cloud Discovery Service (see Section 3.2.1). For that, you can set the environment from the application terminal as follows:

Listing 6.7 Publisher application
 export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0:$OPENSSLHOMELIB
 export BIND_PORT=7401
 export NDDS_DISCOVERY_PEERS=[email protected]_lan://localhost:7400
Listing 6.8 Subscriber application
 export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0:$OPENSSLHOMELIB
 export BIND_PORT=7402
 export NDDS_DISCOVERY_PEERS=[email protected]_lan://localhost:7400

Now run the applications and verify that the subscriber receives samples. You can also stop Cloud Discovery Service and see how the applications continue communicating.

6.5. Example: Using RTI Secure WAN Transport

This example extends Example: Using a built-in UDP transport to use the RTI Secure WAN transport for communication. The example shows how to run Cloud Discovery Service with a user-registered transport instance of the RTI Secure WAN transport.

Note

To run this example you will need RTI Secure Wan Transport and its dependencies. Because DTLS is enabled, you must ensure that OpenSSL libraries are present in your library path before starting the applications. See the beginning of this section for a note on how to locate the OpenSSL libraries.

The provided example uses the WAN transport with security disabled. The WAN transport relies on a rendezvous server based on the STUN protocol in order to locate peers and establish communication. You can run the WAN server as follows:

${NDDSHOME}/bin/rtiwanserver -address <address> -port <port>

Where <address> and <port> define where the WAN server listens and how the publisher and subscriber applications can reach it. In this example, the values for the address and port are 127.0.0.1 and 3478, respectively.

You will need the WAN server to running for all the applications to communicate.

6.5.1. Setup

The first step in this example is to configure the publisher and subscriber applications to communicate over the RTI Secure WAN transport. For that, you can include the following XML code within the <participant_qos> tag of the file USER_QOS_PROFILES.xml generated by rtiddsgen.

<property>
    <value>
        <element>
            <name>dds.transport.load_plugins</name>
            <value>dds.transport.wan_plugin.wan</value>
        </element>
        <element>
            <name>dds.transport.wan_plugin.wan.library</name>
            <value>nddstransportwan</value>
        </element>
        <element>
            <name>dds.transport.wan_plugin.wan.create_function</name>
            <value>NDDS_Transport_WAN_create</value>
        </element>
        <element>
            <name>dds.transport.wan_plugin.wan.server</name>
            <value>127.0.0.1</value>
        </element>
        <element>
            <name>dds.transport.wan_plugin.wan.transport_instance_id</name>
            <value>$(WAN_ID)</value>
        </element>
    </value>
</property>

The WAN ID property value is obtained from the environment variable $(WAN_ID). This is a convenience for this example so you can specify a different ID for the publisher and subscriber without having to modify the file.

Now you can run the applications. You need to run from the directory that contains the generated USER_QOS_PROFILES.xml that you just modified.

Listing 6.9 Publisher application
export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0:$OPENSSLHOMELIB
export WAN_ID=2
export NDDS_DISCOVERY_PEERS=wan://::3:127.0.0.1

./objs/x64Linux3gcc5.4.0/CDSHelloWorld_publisher
Listing 6.10 Subscriber application
export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0:$OPENSSLHOMELIB
export WAN_ID=3
export NDDS_DISCOVERY_PEERS=wan://::2:127.0.0.1

./objs/x64Linux3gcc5.4.0/CDSHelloWorld_subscriber

You should see the subscriber receive samples. This is possible since in the initial peers list, you indicated how the applications can reach each other.

6.5.2. Cloud Discovery Service in action

Now you will use Cloud Discovery Service to provide discovery for the applications. In this case, you need to configure the transport with a user-registered instance of the RTI Secure WAN transport.

The configuration required for this example is shown below:

<?xml version="1.0"?>
<dds  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="http://community.rti.com/schema/latest/rti_cloud_discovery_service.xsd">
            
    <cloud_discovery_service name="ExampleWan">
        <annotation>
            <documentation><![CDATA[ 
                Example that configures an user-registered instance of the
                RTI WAN transport.
                ]]>                
            </documentation>
        </annotation>
        <transport>     
            <element>
                <alias>wan</alias>
                <receive_port>7400</receive_port>
                <property>
                    <element>
                        <name>dds.transport.load_plugins</name>
                        <value>dds.transport.wan_plugin.wan</value>
                    </element>
                    <element>
                        <name>dds.transport.wan_plugin.wan.library</name>
                        <value>nddstransportwan</value>
                    </element>
                    <element>
                        <name>dds.transport.wan_plugin.wan.create_function</name>
                        <value>NDDS_Transport_WAN_create</value>
                    </element>
                    <element>
                        <name>dds.transport.wan_plugin.wan.server</name>
                        <value>127.0.0.1</value>
                    </element>
                    <element>
                        <name>dds.transport.wan_plugin.wan.transport_instance_id</name>
                        <value>1</value>
                    </element>                    
                </property>
            </element>
        </transport>        
    </cloud_discovery_service>
    
</dds>

You can download the configuration file from here: rti_cds_example_wan.xml

From a terminal, run the following command:

$NDDSHOME/bin/rticlouddiscoveryservice \
        -cfgFile <working_dir>/rti_cds_example_wan.xml -cfgName ExampleWan

This command will run Cloud Discovery Service with the custom configuration for this example, located under the directory <working_dir>.

Re-run the publisher and subscriber application, but this time set the initial peers to talk to Cloud Discovery Service (see Section 3.2.1). For that, you can set the environment in the application terminal as follows:

Listing 6.11 Publisher application
 export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0:$OPENSSLHOMELIB
 export WAN_ID=2
 export NDDS_DISCOVERY_PEERS=[email protected]://::1:127.0.0.1:7400
Listing 6.12 Subscriber application
 export LD_LIBRARY_PATH=$NDDSHOME/lib/x64Linux3gcc5.4.0:$OPENSSLHOMELIB
 export WAN_ID=3
 export NDDS_DISCOVERY_PEERS=[email protected]://::1:127.0.0.1:7400

Now run the applications and verify that the subscriber receives samples. You can also stop Cloud Discovery Service and see how the applications continue communicating.