Channels ▼
RSS

Embedded Systems

OMG's Data Distribution Service Standard


An Example DDS Application

Figure 5 shows a concrete but simple distributed application. An embedded single-board computer (SBC) is hardwired to a temperature sensor and connected to an Ethernet transport. It is responsible for gathering temperature sensor data at a specific rate. A workstation, also connected to the network, is responsible for displaying that data on a screen for an operator to view. A variation of this scenario can have multiple temperature sensors wired to the embedded computer each periodically providing the temperature measurement at a different spot, and multiple workstations interested in processing the temperature measurements.

Figure 5: An embedded single-board computer publishes temperature data. A display workstation subscribes to the data.

Identify the domains, participants, topics

The first step to in creating this example is to identify the communication domains, and the participants and topics in each domain. In general, an application can belong to multiple domains as in Figure 6 by creating several DomainParticipants. Multiple domains provide effective data isolation. For example, in a very large systems, it make make sense to have different domains for each functional area in overall system, or to add experimental functionality in a new domain.

Figure 6: Multiple domains provide effective data isolation. Three applications are communicating Command/Control data in Domain A, three other applications are communicating Status data in Domain B, and two other applications are communicating in Domain C.

For this example, the distributed application will use a single domain comprising two participants and a single topic called "Temperature" for exchanging sensor data. A participant on the embedded computer publishes updates to the "Temperature" topic; a participant on the workstation that subscribes to the "Temperature"topic. Additional processing workstations can receive the sensor measurements simply by creating participants that subscribe to the "Temperature" topic.

Define the topic data types and generate data type support code

Since Topics are strongly typed in DDS, the next step is to define the data types associated with the topics. We define a type "SensorInfo" (Example 1) in the OMG Interface Description Language (IDL) since DDS middleware can support multiple language bindings. The SensorInfo data type contains an "id" field to identify the temperature sensor (when multiple temperature sensors are attached to the embedded computer), and a "value" field to specify the measured temperature value. The "id" field is marked as a "key" field; this lets the DDS middleware distinguish between updates from different sensors.

struct SensorInfo {
    long id; //@key
    long value;
};
Example 1

Given the IDL type definition, a DDS middleware provided code generator is used to generate language specific code to deal with the data type. The generate code will contain a definition of the type in the target language (C++ in our example), standard type specific APIs specified by DDS, and middleware implementation specific code.

For the SensorInfo data type, the following standard classes are generated: SensorInfoTypeSupport, SensorInfoDataWriter, SensorInfoDataReader.

Common steps in writing a participant application

The steps in writing a participant application are common, whether it is a publishes or subscribes to data.

1. Create a DomainParticipant.

A DomainParticipant is created bound to a domain as in Example 2, using the DDS standard APIs.

DDSDomainParticipantFactory* factory = NULL;
DDSDomainParticipant* participant = NULL;
DDS_DomainParticipantQos participant_qos;
DDS_DomainId_t domain_id = 10;

factory = DDSDomainParticipantFactory::get_instance();
if (factory == NULL) { /* handle error */ }

factory->get_default_participant_qos(participant_qos);

participant = factory->create_participant(domain_id, 
                                          participant_qos, 
                                          NULL /* participant_listener*/);
if (participant == NULL) { /* handle error */ }
Example 2

2. Register user data types

The generated SensorInfoTypeSupport::register_type() standard method is used to make the type available for use by the DomainParticipant as in Example 3.

DDS_ReturnCode_t retcode;

retcode = SensorInfoTypeSupport::register_type(participant, "SensorInfo");

if (retcode != DDS_RETCODE_OK) { /* handle error */ }

Example 3

3. Create Topics

A named Topic is created bound to a registered user data type as in Example 4 using the standard DDS APIs. A Topic is automatically establishes a data flow between its DataWriters and DataReaders.

DDS_TopicQos topic_qos;
DDSTopic* topic = NULL;

participant->get_default_topic_qos(topic_qos);

topic = participant->create_topic("Temperature", "SensorInfo",
                                  topic_qos, 
                      NULL /* topic_listener*/);

if (topic == NULL) { /* handle error */ }
Example 4

4. Write the publishing participant application

The publishing application on the embedded computer creates a Publisher and a DataWriter as follows.

5. Create Publishers

Given a DomainParticipant, a Publisher is created as shown in Example 5. A Publisher groups a set of DataWriters for different Topics. It also provides methods to suspend/resume publications, and for batching coherent changes.

DDS_PublisherQos publisher_qos;
DDSPublisher* publisher = NULL;

participant->get_default_publisher_qos(publisher_qos);

publisher = participant->create_publisher(publisher_qos, 
                                          NULL /* publisher_listener */);
if (publisher == NULL) { /* handle ... error */ }
Example 5

6. Create DataWriters

Given a Publisher and a Topic belonging to the same DomainParticipant, a strongly typed SensorInfoDataWriter is created as in Example 6. The DataWriter provides methods to send data samples, and manage the lifecycle of a keyed data channel.

DDS_DataWriterQos writer_qos;
SensorInfoDataWriter *writer = NULL;

publisher->get_default_datawriter_qos(writer_qos);

writer = publisher->create_datawriter(topic,
                                      writer_qos, 
                                      NULL /* writer_listener */);
if (writer == NULL) { /* handle error */ }
Example 6

7. Send data updates

Given a SensorInfoDataWriter, new updated values of SensorInfo are published to the subscribers using the SensorInfoDataWriter::write() method, as in Example 7.

SensorInfo sensor_info;   
DDS_InstanceHandle_t sensor_instance_handle = DDS_HANDLE_NIL; 
DDS_ReturnCode_t retcode;

while (1) {

    /* gather_sensor_measurement(&sensor_info); */

   retcode = writer->write(sensor_info, sensor_instance_handle);

   if (retcode != DDS_RETCODE_OK) { /* handle failure */ }
}
Example 7

Figure 7 summarizes the key objects involved in sending data samples (updates) the subscribers of the associated Topic.

Figure 7: A strongly typed DataWriter (DW) sends data samples S Q(updates) to all the subscribers of the associated Topic.

8. Write the subscribing participant application

The subscribing application on the display workstation creates a Subscriber and a DataReader as follows.

Given a DomainParticipant, a Subscriber is created as shown in Example 8. A Subscriber groups a set of DataReaders for different Topics. It also provides methods for ordered access to the received samples across the DataReaders.

DDS_SubscriberQos subscriber_qos;
DDSSubscriber* subscriber = NULL;

participant->get_default_subscriber_qos(subscriber_qos);

subscriber = participant->create_subscriber(subscriber_qos, 
                                            NULL /* subscriber_listener*/);
if (subscriber == NULL) { /* handle error */ }
Example 8

9. Create DataReaders

Given a Subscriber and a Topic belonging to the same DomainParticipant, a strongly typed SensorInfoDataReader is created as in Example 9. The SensorInfoDataReader object is attached to a DataReaderListener, whose on_data_available() method is invoked to process data samples as they are received.

DDS_DataReaderQos reader_qos;
SensorInfoDataReader* reader = NULL;

DDSDataReaderListener* reader_listener = new MyReaderListener(); 

subscriber->get_default_datareader_qos(reader_qos);

reader = subscriber->create_datareader(topic,
                                       reader_qos, 
                                       reader_listener);
if (reader == NULL) { /* handle error */ }
Example 9

Note that DDS also provides a "wait-based" access scheme that lets a caller wait for data to become available. A caller can also poll for available data. In addition a DataReader provides methods to wait for historical data samples and peek at available data samples.

9. Receive data samples

The MyReaderListener::on_data_available() method is called when data samples are available for retrieval by the application. The received SensorInfo data samples that match a desired state criteria are taken from the DDS middleware using the SensorInfoDataReader::take() method, as in Example 10. The "data_seq" contains a sequence of SensorInfo samples; "info_seq" contains additional information about the state of each sample. The contents of these sequences are loaned my the middleware to the application. After the data samples, the application must return the loan by calling SensorInfoDataReader::return_loan().

class MyReaderListener : public DDSDataReaderListener {
  public:
    virtual void on_data_available(DDSDataReader* reader);
};

void MyReaderListener::on_data_available(DDSDataReader* reader)
{
    SensorInfoDataReader *myReader = (SensorInfoDataReader *)reader;
    SensorInfoSeq data_seq;
    DDS_SampleInfoSeq info_seq;
    DDS_ReturnCode_t retcode;
    int i;

    retcode = myReader->take(data_seq, info_seq, 
                    DDS_LENGTH_UNLIMITED, 
                    DDS_ANY_SAMPLE_STATE, 
                    DDS_ANY_VIEW_STATE, 
                    DDS_ANY_INSTANCE_STATE);

    if (retcode != DDS_RETCODE_OK) { /* handle error */ }

    for (i = 0; i < data_seq.length(); ++i) {
        /* display_sensor_measurement(&data_seq[i]); */
    }

    myReader->return_loan(data_seq, info_seq);
}
Example 10

Figure 8 summarizes the key objects involved in receiving data samples (updates) from the publishers of the associated Topic.

Figure 8: A strongly typed DataReader (DR) receives data samples S (updates) from the publishers of the associated Topic.


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 

Embedded Systems Recent Articles

Video

Upcoming Events



Most Recent Premium Content