Generic DDS subscriber

Overview

rtctkGenDdsSub is a troubleshooting tool to subscribe to DDS Agnostic DDS topic(s). It can be used to verify if the DDS agnostic topic data is being published. For example, it can be used to determine if the DDS topic can be received on a particular machine, and the frequency of the incoming data. When used with Generic MUDPI publisher standalone tool and the setting to produce pattern data, it is possible to check the received data for consistency. It can be run instead of (or in parallel with) other DDS subscribers like Telemetry Subscriber. For troubleshooting and diagnosis of FastDDS-related problems, some additional tools like fastddsMonitor can be used. These additional tools are provided as part of FastDDS.

Prerequisites

Similar to other DDS-based applications, the generic DDS subscriber uses FastDDS as well. Its DDS QoS is configured using the default XML file telemDataPathDdsQos.xml which is installed in $INTROOT/resource/config/rtctk/dds/. A different file can be specified using the --qos-file command line option. The file needs to be located under rtctk/dds/ in the $CFGPATH.

Note

FASTDDS_DEFAULT_PROFILES_FILE environment variable shall not be used (set). In particular, if the file that the variable points to contains the same QoS profiles.

Running

The generic DDS subscriber is run by executing rtctkGenDdsSub with the appropriate command-line arguments.

For a complete list of command-line options, run:

$ rtctkGenDdsSub --help

For example, to subscribe to three topics:

$ rtctkGenDdsSub -d -t test_topic_0 test_topic_1 test_topic_2

Payload validation

Payload validation can be enabled with the --expected-payload-pattern option. Currently, alternating_float_ramp is supported. This is useful when subscribing to DDS samples produced from MUDPI input generated by rtctkGenMudpiPub with --payload-pattern alternating_float_ramp.

For example, to subscribe to test_topic_00 and validate that the received DDS samples contain the expected floating-point alternating ramp payload, run:

$ rtctkGenDdsSub -d --expected-payload-pattern alternating_float_ramp -t test_topic_00

The legacy -c/--check-ramp option checks for the older floating-point ramp format. For payloads generated by rtctkGenMudpiPub with --payload-pattern alternating_float_ramp, use --expected-payload-pattern alternating_float_ramp.

Reception modes

rtctkGenDdsSub supports two DDS reception modes:

waitset: Receives samples synchronously using DdsWaitSet. This is the default reception mode and is used when the --reception-mode option is omitted.
listener: Receives samples asynchronously through the Fast DDS on_data_available() listener callback.

Both reception modes use the same sample-processing logic for sample-ID validation, payload validation, counters, statistics, and diagnostic output. Only the mechanism used to receive the DDS samples is different.

The listener mode can be useful for troubleshooting and for comparing the behavior of callback-based reception with WaitSet-based reception.

To use the default WaitSet reception mode explicitly:

$ rtctkGenDdsSub \
    --reception-mode waitset \
    -t test_topic_0 test_topic_1 test_topic_2

Because waitset is the default, the following command is equivalent:

$ rtctkGenDdsSub \
    -t test_topic_0 test_topic_1 test_topic_2

To use the asynchronous listener reception mode:

$ rtctkGenDdsSub \
    --reception-mode listener \
    -t test_topic_0 test_topic_1 test_topic_2

An unsupported reception mode causes the tool to terminate with an error. For example:

$ rtctkGenDdsSub --reception-mode invalid

ERROR: Unsupported reception mode 'invalid'. Expected 'waitset' or 'listener'.

Diagnostic output

Messages are logged every 60 seconds with samples for each subscribed topic with the number of received samples, the average time between sample receiving, the estimated (receiving) frequency, and sample errors so far. E.g. for TestTopic0, TestTopic1 and TestTopic2:

...
[2023-07-03 14:36:05.166][INFO ][rtctk] [test_topic_2][2]        Total sample received: 23015 Avg: 0.0026070032611340533. Freq: 383.58218223516815. Total sample errors so far: 0
[2023-07-03 14:36:05.167][INFO ][rtctk] [test_topic_1][1]        Total sample received: 23015 Avg: 0.002607092641060195. Freq: 383.56903174462644. Total sample errors so far: 0
[2023-07-03 14:36:05.167][INFO ][rtctk] [test_topic_0][0]        Total sample received: 23016 Avg: 0.0026069003169534215. Freq: 383.5973295552242. Total sample errors so far: 0
...

Messages indicating that a particular topic (e.g. TestTopic0) is there for the DDS publisher and that the process is subscribed to it, as well as the payload size of the first received sample are also logged. These messages are printed before any data is received. For example:

[2023-07-03 14:35:04.927][INFO ][rtctk] [test_topic_0][0] alive_count: 1 not_alive_count: 0 alive_count_change: 1 not_alive_count_change: 0
[2023-07-03 14:35:05.125][INFO ][rtctk] [test_topic_0][0] SampleId: 1 Payload size: 50000

The following message indicates that a DDS publisher for a particular topic (e.g. TestTopic0) is gone:

[2023-07-03 14:41:28.733][INFO ][rtctk] [test_topic_0][0] alive_count: 0 not_alive_count: 0 alive_count_change: -1 not_alive_count_change: 0

Stopping

The process can be stopped using Ctrl-C.