2. Introduction to Publish/Subscribe

Prerequisites
Time to complete 30 minutes
Concepts covered in this module
  • Introduction to publish/subscribe
  • Introduction to DataWriters, and DataReaders, and Topics
  • Using the code generator
  • Using Waitsets
  • Viewing your data in RTI Admin Console

The most basic communication pattern supported by RTI® Connext® DDS is the publish/subscribe model. Publish/Subscribe is a communications model where data producers “publish” data and data consumers “subscribe” to data. These publishers and subscribers don’t need to know about each other ahead of time; they discover each other dynamically at runtime. The data they share is described by a “topic,” and publishers and subscribers send and receive data only for the topics they are interested in. In this pattern, many publishers may publish the same topic, and many subscribers may subscribe to the same topic. Subscribers receive data from all of the publishers that they share a topic with. Publishers send data directly to subscribers, with no need for a broker or centralized application to mediate communications.

2.1. Introduction to DataWriters, DataReaders, and Topics

In DDS, the objects that actually publish data are called DataWriters, and the objects that subscribe to data are DataReaders. DataWriters and DataReaders are associated with a single Topic object that describes that data. (DDS also has Publisher and Subscriber objects, but we will talk about them later.) An application typically has a combination of DataWriters and DataReaders.

Writers Readers Overview

Figure 2.1 DataWriters write data and DataReaders read data of a Topic. DataWriters of the “ChocolateTemperature” Topic communicate with DataReaders of the “ChocolateTemperature” Topic. DataWriters of the “ChocolateLotState” Topic communicate with DataReaders of the “ChocolateLotState” Topic.

In a chocolate factory, for example, there might be a sensor that measures and publishes the current temperature of the tempering machine. Other applications monitor the temperature by subscribing to it. In this example, your Topic might be “ChocolateTemperature.” The sensor’s DataWriter will be associated with the “ChocolateTemperature” Topic. In a similar way, other DataWriters and DataReaders share different types of data using additional Topics.

Connext DDS is responsible for discovering DataWriters and DataReaders in a system, checking if they have a matching Topic (and compatible quality of service, which we will discuss later) and then providing the communication between those DataWriters and DataReaders. Logically, this means you can visualize your applications as having DataWriters and DataReaders that connect to a “databus,” because your applications are not specifying exactly which other applications they communicate with – they only specify which Topics they read from and write to the databus, and Connext DDS sets up the communication. Note that there is no “databus” object in your system – it is a logical way to visualize systems in which you don’t have to configure each communication path.

2.2. Hands-On 1: Your First DataWriter and DataReader

We are going to start with a simple “Hello World” application to show how to use the code generator, and how to create a DataWriter and a DataReader.

Tip

By the end of this exercise, a publishing application will send data, and a subscribing application will receive and print it to the console using HelloWorldTypeSupport::print_data().

2.2.1. Clone Repository

Get the files you need to perform the hands-on exercises. Either download the repository as a Zip file from the repository webpage here, or clone the repository from GitHub with the following command:

$ git clone https://github.com/rticommunity/rticonnextdds-getting-started.git
$ git clone https://github.com/rticommunity/rticonnextdds-getting-started.git
> git clone https://github.com/rticommunity/rticonnextdds-getting-started.git

2.2.2. Set Up Environment Variables (rtisetenv)

Set up the environment variables for running the code generator and compiling your application:

  1. Open a command prompt window, if you haven’t already.

  2. Run this script:

    $ source <installdir>/resource/scripts/rtisetenv_<architecture>.bash
    
    $ source <installdir>/resource/scripts/rtisetenv_<architecture>.bash
    

    If the script doesn’t work, you may be using the zsh shell. If you are, run /bin/bash before running the script to get into the bash shell.

    > <installdir>\resource\scripts\rtisetenv_<architecture>.bat
    

    When a directory name has a space, enclose the path in quotation marks. For example: "C:\Program Files\rti_connext_dds-6.0.1\resource\scripts\rtisetenv_x64Win64VS2017.bat".

    <installdir> refers to the installation directory for Connext DDS.

    The rtisetenv script adds the location of the SDK libraries (<installdir>/lib/<architecture>) to your library path, sets the <NDDSHOME> environment variable (see Paths Mentioned in Documentation), and puts the RTI Code Generator tool in your path. You’ll need this tool in the next step.

    Your architecture (such as x64Win64VS2017 or x64Linux3gcc5.4.0) is the combination of a processor, OS, and compiler version that you will use to build your application. The architecture you choose should match the target libraries you installed (see Installing Connext DDS). See also Checking What is Installed. To see the full list of available architectures, run rtiddsgen -help or see the “RTI Architecture Abbreviation” columns in the RTI Connext DDS Core Libraries Platform Notes.

    If this script does not exist in your installation, it means that you need to install a target. See Installing Connext DDS.

2.2.3. Run Code Generator

Inside the repository you have cloned, there is a directory named 2_hello_world, which contains the HelloWorld type definition in a file named hello_world.idl.

  1. Open hello_world.idl to see the definition for our HelloWorld type:

    // Hello world!
    struct HelloWorld {
    
        // String with maximum length of 256 characters
        string<256> msg;
    
    };
    

    This language-independent interface is written in IDL, the Interface Definition Language. IDL allows you to declare data types used for communication (we’ll cover this more in Introduction to Data Types). Connext DDS includes a code generator that translates from this language-independent data type into code specific for your language. The generated code serializes and deserializes your data into and out of a network format.

  2. From a terminal or command prompt, run rtiddsgen, which runs the code generator on hello_world.idl:

    $ cd 2_hello_world
    $ rtiddsgen -language c++ -platform <architecture> -create makefiles -create typefiles -d c++98 hello_world.idl
    
    $ cd 2_hello_world
    $ rtiddsgen -language c++ -platform <architecture> -create makefiles -create typefiles -d c++98 hello_world.idl
    
    > cd 2_hello_world
    > rtiddsgen -language c++ -platform <architecture> -create makefiles -create typefiles -d c++98 -ppDisable hello_world.idl
    

    -ppDisable disables the preprocessor. It is necessary for running rtiddsgen on a Windows system if the preprocessor is not in your path. You can only use -ppDisable if your IDL is simple, as it is here—otherwise you must add the preprocessor to your path. See Command-Line Arguments for rtiddsgen, in the RTI Connext DDS Code Generator User’s Manual if you want more information.

    You don’t have to type the full path (<install dir>/bin/rtiddsgen) because you ran rtisetenv_<architecture> earlier, as described in Set Up Environment Variables (rtisetenv).

    Your architecture is the combination of a processor, OS, and compiler version that you will use to build your application. (See Set Up Environment Variables (rtisetenv).)

    -d c++98 specifies the directory where the code will be generated.

    Note

    If you are using Visual Studio 2019, use “VS2017” in your architecture name.

  3. Open the c++98 directory to review the code.

2.2.3.1. Overview of Generated and Example Code

The code you just generated includes the files in Table 2.1, in the c++98 directory. Some of the files are generated by rtiddsgen, some came from the git repository you cloned.

Table 2.1 Generated and Example Code Files
Files Description Generated by rtiddsgen?
  • hello_world.h
  • hello_world.cxx
  • hello_worldPlugin.h
  • hello_worldPlugin.cxx
  • hello_worldSupport.h
  • hello_worldSupport.cxx
The C++98 definition of your data type, and the code used to serialize and deserialize it (convert it to a format for the network). This is the type-specific code that will be used in your real application. These files were generated when you specified -create typefiles when running rtiddsgen. Yes
  • application.hpp
  • hello_world_publisher.cxx
  • hello_world_subscriber.cxx
Example code from the repository you cloned. It includes code for two applications you can read and modify. These will compile into separate applications, hello_world_publisher and hello_world_subscriber. No [1]
  • makefiles, Visual Studio solutions, or project files
Used to build your application. These files were generated because you specified -platform <architecture> -create makefiles when running rtiddsgen. For more information on how to build, see the README_<architecture>.txt file generated with the code. [2] Yes
  • USER_QOS_PROFILES.xml
Configuration file for Quality of Service (to be discussed more later). This file came from the repository you cloned. No
  • README_<architecture>.txt
Instructions for how to open and modify the files, compile, and run the example for your specific IDE and operating system. This file was generated when you ran rtiddsgen. Yes
[1]rtiddsgen can also generate simple example code, but we are using our own code examples for this Getting Started Guide.
[2]These files are generated by rtiddsgen. If you want to create your own project files or makefiles, see the RTI Connext DDS Core Libraries Platform Notes to know what compilation and linker settings to use in them.

2.2.4. Open/Modify Publishing Application

  1. In the 2_hello_world/c++98 directory, open hello_world_publisher.cxx in your IDE of choice. (See the README_<architecture>.txt file generated with the code for information on how to modify this file in your IDE and operating system.)

    This snippet shows how to create a Topic (with a name and data type) and create a DataWriter for that Topic:

    // A Topic has a name and a datatype. Create a Topic called
    // "HelloWorld Topic" with your registered data type
    DDSTopic *topic = participant->create_topic(
            "Example HelloWorld",
            type_name,
            DDS_TOPIC_QOS_DEFAULT,
            NULL /* listener */,
            DDS_STATUS_MASK_NONE);
    if (topic == NULL) {
        return shutdown(participant, "create_topic error", EXIT_FAILURE);
    }
    
    // This DataWriter will write data on Topic "HelloWorld Topic"
    // DataWriter QoS is configured in USER_QOS_PROFILES.xml
    DDSDataWriter *writer = publisher->create_datawriter(
            topic,
            DDS_DATAWRITER_QOS_DEFAULT,
            NULL /* listener */,
            DDS_STATUS_MASK_NONE);
    if (writer == NULL) {
        return shutdown(participant, "create_datawriter error", EXIT_FAILURE);
    }
    
    // A narrow is a cast from a generic DataWriter to one that is specific
    // to your type. Use the type specific DataWriter to write()
    HelloWorldDataWriter *hello_world_writer =
            HelloWorldDataWriter::narrow(writer);
    if (hello_world_writer == NULL) {
        return shutdown(participant, "DataWriter narrow error", EXIT_FAILURE);
    }
    
  2. Change the Topic name from “Example HelloWorld” to “HelloWorld Topic”:

    // A Topic has a name and a datatype. Create a Topic called
    // "HelloWorld Topic" with your registered data type
    DDSTopic *topic = participant->create_topic(
            "HelloWorld Topic",
            type_name,
            DDS_TOPIC_QOS_DEFAULT,
            NULL /* listener */,
            DDS_STATUS_MASK_NONE);
    if (topic == NULL) {
        return shutdown(participant, "create_topic error", EXIT_FAILURE);
    }
    
  3. Modify the code to send the message “Hello world!” with a count.

    The following snippet shows how to write a HelloWorld update using the DataWriter’s write method.

    In the for loop in the snippet, add the highlighted line, just after the comment // Modify the data to be written here. This will set sample.msg to “Hello world!” with a count:

    // Create data sample for writing
    HelloWorld *sample = HelloWorldTypeSupport::create_data();
    if (sample == NULL) {
        return shutdown(
                participant,
                "HelloWorldTypeSupport::create_data error",
                EXIT_FAILURE);
    }
    
    // Main loop, write data
    // ---------------------
    for (unsigned int count = 0;
         running && ((sample_count == 0) || (count < sample_count));
         ++count) {
        // Modify the data to be written here
        snprintf(sample->msg, 256, "Hello world! %d", count);
    
        std::cout << "Writing HelloWorld, count " << count << std::endl;
        retcode = hello_world_writer->write(*sample, DDS_HANDLE_NIL);
        if (retcode != DDS_RETCODE_OK) {
            std::cerr << "write error " << retcode << std::endl;
        }
    
        // Send every 4 seconds
        DDS_Duration_t send_period = { 4, 0 };
        NDDSUtility::sleep(send_period);
    }
    

    Recall that your “HelloWorld Topic” describes your data. This Topic is associated with the data type HelloWorld, which is defined in the IDL file (see Run Code Generator). The data type HelloWorld contains a string field named msg. In this step, you have just added code to set a value for the msg field. Now, when the DataWriter writes data, the msg field in the data will contain the string “Hello world! 1”, “Hello world! 2”, etc.

Definition

A sample is a single update to a Topic, such as “Hello world! 1”. Every time an application calls write(), it is “writing a sample.” Every time an application receives data, it is “receiving a sample.”

Note that samples don’t necessarily overwrite each other. For example, if you set up a RELIABLE Quality of Service (QoS) with a History kind of KEEP_ALL, all samples will be saved and accumulate. You can find more details in Basic QoS.

2.2.5. Open/Modify Subscribing Application

The subscriber application also creates a Topic, in hello_world_subscriber.cxx.

  1. Open hello_world_subscriber.cxx.

    This snippet shows how to create a Topic (with a name and data type) and create a DataReader for that Topic:

    // A Topic has a name and a datatype. Create a Topic called
    // "HelloWorld Topic" with your registered data type
    DDSTopic *topic = participant->create_topic(
            "Example HelloWorld",
            type_name,
            DDS_TOPIC_QOS_DEFAULT,
            NULL /* listener */,
            DDS_STATUS_MASK_NONE);
    if (topic == NULL) {
        shutdown(participant, "create_topic error", EXIT_FAILURE);
    }
    
    // This DataReader will read data of type HelloWorld on Topic
    // "HelloWorld Topic". DataReader QoS is configured in
    // USER_QOS_PROFILES.xml
    DDSDataReader *reader = subscriber->create_datareader(
            topic,
            DDS_DATAREADER_QOS_DEFAULT,
            NULL,
            DDS_STATUS_MASK_NONE);
    if (reader == NULL) {
        shutdown(participant, "create_datareader error", EXIT_FAILURE);
    }
    
  2. Change the Topic name from “Example HelloWorld” to “HelloWorld Topic”, just as you did in the publishing application.

    Note

    The Topic names must match between the publishing and subscribing applications for the DataWriter and DataReader to communicate.

    // A Topic has a name and a datatype. Create a Topic called
    // "HelloWorld Topic" with your registered data type
    DDSTopic *topic = participant->create_topic(
            "HelloWorld Topic",
            type_name,
            DDS_TOPIC_QOS_DEFAULT,
            NULL /* listener */,
            DDS_STATUS_MASK_NONE);
    if (topic == NULL) {
        shutdown(participant, "create_topic error", EXIT_FAILURE);
    }
    

2.2.5.1. Details of Receiving Data

You don’t need to make any changes here, but look at the hello_world_subscriber.cxx code to see how it receives data. The DataReader is being notified of new data using an object called a WaitSet:

// Get status condition: Each entity has a Status Condition, which
// gets triggered when a status becomes true
DDSStatusCondition *status_condition = reader->get_statuscondition();
if (status_condition == NULL) {
    shutdown(participant, "get_statuscondition error", EXIT_FAILURE);
}

// Enable only the status we are interested in:
//   DDS_DATA_AVAILABLE_STATUS
retcode = status_condition->set_enabled_statuses(DDS_DATA_AVAILABLE_STATUS);
if (retcode != DDS_RETCODE_OK) {
    shutdown(participant, "set_enabled_statuses error", EXIT_FAILURE);
}

// Create the WaitSet and attach the Status Condition to it. The WaitSet
// will be woken when the condition is triggered.
DDSWaitSet waitset;
retcode = waitset.attach_condition(status_condition);
if (retcode != DDS_RETCODE_OK) {
    shutdown(participant, "attach_condition error", EXIT_FAILURE);
}

// A narrow is a cast from a generic DataReader to one that is specific
// to your type. Use the type specific DataReader to read data
HelloWorldDataReader *hello_world_reader =
        HelloWorldDataReader::narrow(reader);
if (hello_world_reader == NULL) {
    shutdown(participant, "DataReader narrow error", EXIT_FAILURE);
}

// Main loop. Wait for data to arrive, and process when it arrives.
// ----------------------------------------------------------------
unsigned int samples_read = 0;
while (running && (samples_read < sample_count || sample_count == 0)) {
    DDSConditionSeq active_conditions_seq;

    // wait() blocks execution of the thread until one or more attached
    // Conditions become true, or until a user-specified timeout expires.
    DDS_Duration_t wait_timeout = { 4, 0 };
    retcode = waitset.wait(active_conditions_seq, wait_timeout);

This WaitSet object is a way for the application to sleep until some “condition” becomes true. When the application calls waitset.wait(active_conditions_seq, wait_timeout), it will sleep for up to the duration time (4 seconds in this example), unless it is woken up due to a condition becoming true.

There are multiple types of conditions that you can attach to a WaitSet, but this example shows a StatusCondition. In this example, we are saying that we are interested in waking up when the “data available” status becomes true. This means that when data arrives:

  • The reader’s data_available status becomes true
  • The application is woken up from the wait() call
  • The application code to process the status condition gets called

Here is the code that gets run when the StatusCondition becomes true:

// Get the status changes to check which status condition
// triggered the WaitSet to wake
DDS_StatusMask triggeredmask =
        hello_world_reader->get_status_changes();
// If the status is "Data Available"
if (triggeredmask & DDS_DATA_AVAILABLE_STATUS) {
    samples_read += process_data(hello_world_reader);
}

This code checks that the data_available status became true, and then calls a process_data function. A closer look at process_data:

// Process data. Returns number of samples processed.
unsigned int process_data(HelloWorldDataReader *hello_world_reader)
{
    HelloWorldSeq data_seq;
    DDS_SampleInfoSeq info_seq;
    unsigned int samples_read = 0;

    // Take available data from DataReader's queue
    DDS_ReturnCode_t retcode = hello_world_reader->take(data_seq, info_seq);

    if (retcode != DDS_RETCODE_OK) {
        std::cerr << "take error " << retcode << std::endl;
        return 0;
    }

    // Iterate over all available data
    for (int i = 0; i < data_seq.length(); ++i) {
        // Check if a sample is an instance lifecycle event
        if (!info_seq[i].valid_data) {
            std::cout << "Received instance state notification" << std::endl;
            continue;
        }
        // Print data
        HelloWorldTypeSupport::print_data(&data_seq[i]);
        samples_read++;
    }
    // Data sequence was loaned from middleware for performance.
    // Return loan when application is finished with data.
    hello_world_reader->return_loan(data_seq, info_seq);
}

A closer look at the code for taking data:

// Take available data from DataReader's queue
DDS_ReturnCode_t retcode = hello_world_reader->take(data_seq, info_seq);

if (retcode != DDS_RETCODE_OK) {
    std::cerr << "take error " << retcode << std::endl;
    return 0;
}

This code calls hello_world_reader->take(), which removes any available samples out of the DataReader queue, and returns them in a sequence. If data is arriving quickly, it is likely this sequence will contain multiple samples. In this example, the sample’s data is being printed to the screen with HelloWorldTypeSupport::print_data.

2.2.6. Compile Your Changes

Now that you have made changes to both the publisher and subscriber code, compile the code with your modifications. (For general instructions on how to compile on each operating system, see the README_<architecture>.txt file included with your generated code.)

Note

If you see linker errors, you may not have a complete installation. See Installing Connext DDS.

You should see two applications in the objs/<architecture> directory:

  • hello_world_publisher
  • hello_world_subscriber

2.2.7. Run the Applications

  1. Make sure you have run rtisetenv_<architecture> in any new command prompt window, to avoid issues with paths and licensing. See Set Up Environment Variables (rtisetenv).

  2. From within the 2_hello_world/c++98 directory, enter the following full path:

    $ objs/<architecture>/hello_world_publisher
    
    $ objs/<architecture>/hello_world_publisher
    
    > objs\<architecture>\hello_world_publisher.exe
    

    Note

    You must be in the 2_hello_world/<language> directory and type the full path above. Do not run the publisher or subscriber application from within objs/<architecture>. You should run from the 2_hello_world/<language> directory because the examples use Quality of Service (QoS) information from the file USER_QOS_PROFILES.xml in the 2_hello_world/<language> directory. We’ll talk more about QoS in a later module.

    You should see this in the window for the publisher:

    Writing HelloWorld, count 1
    Writing HelloWorld, count 2
    Writing HelloWorld, count 3
    Writing HelloWorld, count 4
    ...
    
  3. Open another command prompt window, run rtisetenv_<architecture> if you haven’t already in that window, and from within the 2_hello_world/c++98 directory, enter the following full path:

    $ objs/<architecture>/hello_world_subscriber
    
    $ objs/<architecture>/hello_world_subscriber
    
    > objs\<architecture>\hello_world_subscriber.exe
    

    You should see this in the window for the subscriber:

       msg: "Hello world! 1"
    Wait timed out after 4 seconds.
    
       msg: "Hello world! 2"
    Wait timed out after 4 seconds.
    
       msg: "Hello world! 3"
    Wait timed out after 4 seconds.
    
        msg: "Hello world! 4"
    ...
    

    (Since the wait_timeout for both the publisher and subscriber is up to 4 seconds, you may or may not get the Wait timed out after 4 seconds line between the samples, depending on the timing between the two applications.)

    The msg: "Hello world! <count>" line is the data being sent by the DataWriter. If the DataWriter weren’t communicating with the DataReader, you would just see the Wait timed out after 4 seconds lines and not the “msg” lines. (The subscribing application prints the “timed out” lines after the WaitSet times out while waiting for data, then it prints the “msg:” lines when it receives data from the DataWriter.)

    Note

    If you don’t get the results described here, see Troubleshooting.

2.2.8. Taking It Further

Under the hood, the publishing and subscribing applications are doing a lot of work:

Before communication starts, the DataWriter and DataReader discover each other and check that they have the same Topic name, compatible data types, and compatible QoS. (We will talk more about discovery in a later module). After discovery, the DataWriter sends data directly to the DataReader, with no message broker required.

When you run the applications on the same machine, by default they communicate over shared memory. If you run one on another machine, they communicate over the network using UDP.

2.2.8.1. Start up Multiple Publishing or Subscribing Applications

Try starting up multiple publishing or subscribing applications, and you will see that they will also send or receive data. (Remember to run from the 2_hello_world/<language> directory.)

Hello World Publisher Subscriber

Figure 2.3 Two applications publishing, and two subscribing, to the same Topic. Notice that each subscriber is receiving data from both publishers.

Two Applications Publishing and Subscribing

Figure 2.4 Two applications publishing, and two subscribing, to the same Topic.

2.2.8.2. Publish/Subscribe across Multiple Machines

To publish/subscribe between two machines:

  1. Clone the repository on both machines. See Clone Repository.

  2. In the 2_hello_world directory on one machine, modify and run the publishing application as described in Open/Modify Publishing Application. See also Compile Your Changes and Run the Applications.

  3. In the 2_hello_world directory on the other machine, modify and run the subscribing application as described in Open/Modify Subscribing Application. See also Compile Your Changes and Run the Applications.

    Note

    If you are running both applications and they aren’t communicating (you don’t see the “msg:” lines shown at the end of Run the Applications), see Troubleshooting.

2.2.8.3. Create Multiple DataWriters, DataReaders, and Topics in a Single Application

So far, you have created two applications: one that uses a DataReader to subscribe to “HelloWorld Topic” and one that uses a DataWriter to publish “HelloWorld Topic.” You have seen that these applications automatically discover each other and communicate, and that you can run multiple copies of them.

In Introduction to Data Types, you’ll add a second DataWriter to an application, and in Introduction to Keys and Instances, you’ll create an application that contains multiple DataWriters, DataReaders, and Topics.

Tip

Even though these initial example applications each do only one thing, typical real-world applications contain a combination of DataWriters and DataReaders for multiple Topics in a single application. We will illustrate this in later modules.

Oven Application, Multiple Topics

Figure 2.5 Sneak Preview: In a later module, we will create a tempering application that will write a “ChocolateTemperature” Topic and read a “ChocolateLotState” Topic. An application can write and read multiple Topics by creating more DataWriters and DataReaders.

2.3. Troubleshooting

2.3.1. Why aren’t my applications communicating?

If you are running both applications and they aren’t communicating (you don’t see the msg: Hello world lines shown at the end of Run the Applications), here are some things to check:

  • Did you change the Topic name in both applications before compiling? They should match.
  • Are you running both applications from the 2_hello_world/<language> directory, so they load the same USER_QOS_PROFILES.xml file?

    Note

    You must be in the 2_hello_world/<language> directory when you type objs/<architecture>/hello_world_<publisher or subscriber>[.exe]. Do not run the application from within objs/<architecture>. (When rtiddsgen generates a project for your IDE (e.g., for Eclipse™ or Visual Studio) and you run the application from that IDE, it will run from the correct directory.)

  • If you are running on multiple machines, does your network support multicast? If it does not, see How do I set my discovery peers? below, for how to specify the addresses of the remote machines your application plans to communicate with.

  • Check to see if one or both machines use a firewall. You may need to disable your firewall or configure it to allow multicast traffic for communication to be established.

For more information, see the article on RTI Community, How to Do Basic Debugging for System-Level DDS.

2.3.2. How do I set my discovery peers?

If you are running Connext DDS on multiple machines and your network does not support multicast, specify the address(es) of the remote machine(s) you want to communicate with:

  1. In the 2_hello_world\<language> directory, find USER_QOS_PROFILES.xml.

  2. Identify the following lines in USER_QOS_PROFILES.xml:

    <participant_qos>
        <!--
        The participant name, if it is set, will be displayed in the
        RTI tools, making it easier for you to tell one
        application from another when you're debugging.
        -->
        <participant_name>
            <name>HelloWorldParticipant</name>
        </participant_name>
    
    </participant_qos>
    
  3. Add the <discovery> section as follows, and replace the IP address with the IP address or hostname of the other machine you want to communicate with:

    <participant_qos>
        <!--
        The participant name, if it is set, will be displayed in the
        RTI tools, making it easier for you to tell one
        application from another when you're debugging.
        -->
        <participant_name>
            <name>HelloWorldParticipant</name>
        </participant_name>
        <discovery>
            <initial_peers>
                <!-- Add an element for each machine you want to communicate with -->
                <element>192.168.1.14</element>
            </initial_peers>
        </discovery>
    
    </participant_qos>
    

If you want more information about discovery peers, see Configuring the Peers List Used in Discovery, in the RTI Connext DDS Core Libraries User’s Manual.

2.3.3. Why does the DataReader miss the first samples?

Discovery is not an instantaneous event. It takes some time for the discovery process between applications to complete. The DataWriter and DataReader must discover each other before they can start communicating. Therefore, if you send data immediately after creating the Connext DDS entities, DataReaders will not receive the first few samples because they are still in-process of discovering the DataWriters and vice versa. This is true even when the DataWriters and DataReaders are reliable, because the Reliability QoS on its own does not guarantee delivery to DataReaders that have not been discovered yet.

You can overcome this behavior with the Durability QoS Policy, which can be set to deliver historical samples (that DataWriters already sent) to late-joining DataReaders. The DataReaders will then receive the first samples they originally missed. We’ll talk about this more in Basic QoS.

2.3.4. Why do I get a “No source for License information” error?

If you get the following error, run rtisetenv_<architecture> in your command prompt window:

RTI Connext DDS No source for License information
Please contact support@rti.com with any questions or comments.
Exception in subscriber_main(): Failed to create DomainParticipant

(You may need to run rtisetenv_<architecture> for each new command prompt window you open, especially if you installed an evaluation version.) See Set Up Environment Variables (rtisetenv). See also Setting Up a License.

2.4. Hands-On 2: Viewing Your Data

Now that you’ve created applications that are publishing data, you can visualize that data using the Admin Console tool.

Note

The applications from Hands-On 1 above should be running while you perform the Admin Console steps below. See Run the Applications.

2.4.1. Open Admin Console

Start by opening Admin Console from RTI Launcher:

Open Admin Console in Launcher

The following sections guide you through Admin Console for the purposes of this exercise, but you can find more information in Admin Console’s online Help:

Admin Console Help

2.4.2. Choose Automatically Join

You may be prompted to automatically or manually join domains when you first open Admin Console. For the purposes of this exercise, choose to automatically join (the default). We’ll discuss domains in a later module.

2.4.3. Switch to Data Visualization Perspective

Select the Data Visualization Perspective entry under the Visualization menu. (You may need to close a Welcome tab first.) If you can’t select the Data Visualization Perspective menu item, you may already be in that mode.

Open Data Visualization

2.4.4. Open Topic Data Tab

From the DDS Logical View, click on the “HelloWorld Topic” to open the Topic View.

Open Topic Data Tab

After switching to the Data Visualization Perspective, the main window will show the Topic Data tab, as seen below:

Topic Data Tab

2.4.5. Subscribe to “HelloWorld Topic”

The Admin Console tool itself is a DDS application, so it must also create DataReaders to subscribe to the “HelloWorld Topic.” (See the Admin Console online Help for more information about this.) When you subscribe to the “HelloWorld Topic” in Admin Console, Admin Console will create a DataReader for this Topic.

Click on the Subscribe… button or right-click on the Topic in the DDS Logical View and select Subscribe. This will open the Create Subscription dialog seen below. Click OK to subscribe to the Topic.

Create Subscription Dialog

2.4.6. Use Topic Data Tab

After the Topic is subscribed to, you will see your “Hello world” message.

View Hello World Message

In the Admin Console tool, you’re also able to inspect DataWriters and DataReaders, and even chart your live data, which we will look at later.

2.4.7. Use Admin Console across Machines

Admin Console is like any other Connext DDS application. It discovers what DataWriters and DataReaders are on the network, whether they’re on the same machine as Admin Console or on different machines.

If you have trouble viewing data in Admin Console across machines, the same troubleshooting tips apply to Admin Console as apply to DataWriters and DataReaders in How do I set my discovery peers?. If your network supports multicast, you’ll see data on the other machines in Admin Console; otherwise, specify the IP addresses of the remote machines you want Admin Console to communicate with.

Setting Peers in Admin Console

2.5. Next Steps

Congratulations! You’ve written your first DDS application, which publishes HelloWorld data. In this exercise, you’ve experienced a quick overview of the development process from defining a data type and using the code generator, to building an example application and using Connext DDS Professional tools to see that data is being published. We’ll continue to build on these skills and to use these tools in more depth in subsequent exercises.

2.5.1. Additional information

See the full RTI Connext DDS Core Libraries Getting Started Guide for more details, including common design patterns such as subscribing only to relevant data and accessing historical data when joining the network. The content in this hands-on exercise (Introduction to Publish/Subscribe) replaces section 4.1 Building and Running “Hello, World” in the full guide.

2.5.2. Next Step

The next module takes a deeper dive into data types, including a little more information about how to define common types. We will be starting to work with an example that’s more complex than a “hello world”—we’re going to be using a chocolate factory example to showcase DDS concepts.

See next: Introduction to Data Types.