Usage

rtiddsspy
      [-help]
      [-version]
      [-domainId <domainId>]     ... defaults to 0
      [-domainTag <domainTag>]   ... defaults to ""
      [-index <NN>]              ... defaults to -1 (auto)
      [-appId <ID>]              ... defaults to a middleware-selected value
      [-verbosity <NN>]          ... can be 0..5
      [-peer <PEER>]             ... PEER format is NN\@TRANSPORT://ADDRESS
      [-discoveryTTL <NN>]       ... can be 0..255
      [-transport <MASK>]        ... defaults to DDS_TRANSPORTBUILTIN_MASK_DEFAULT
      [-msgMaxSize <SIZE>]       ... defaults to -1 (transport default)
      [-shmRcvSize <SIZE>]       ... defaults to -1 (transport default)
      [-tcMaxSize <SIZE>]        ... defaults to 4096
      [-qosFile <file>]
      [-qosProfile <lib::prof>]

      [-hOutput]
      [-mode <USER|DISC>]
      [-deadline <SS>]         ... defaults to -1 (no deadline)
      [-discoveryPlugins <SDP|SDP2>]   ... defaults to SDP
      [-timeFilter <SS>]         ... defaults to  0 (no filter)
      [-history <DEPTH>]       ... defaults to 8192
      [-participantPartition <partition>]   ... defaults to *
      [-subscriberPartition <partition>]   ... defaults to *
      [-useFirstPublicationQos]
      [-showHandle]
      [-showSampleFlags]
      [-showSampleIdentity]
      [-typeRegex <REGEX>]       ... defaults to "*"
      [-topicRegex <REGEX>]      ... defaults to "*"
      [-typeWidth <WIDTH>]        ... can be 1..255
      [-topicWidth <WIDTH>]       ... can be 1..255
      [-printSample <PLAIN|COMPACT>]  ... default PLAIN
      [-showEntityName]
      [-showPartition]

Example:

rtiddsspy -domainId 3 -topicRegex "Alarm*"

To run rtiddsspy, like any DDS application, you must set the NDDS_DISCOVERY_PEERS environment variable that defines your DDS domain; otherwise you must specify the peers as command-line parameters. See How do I set my discovery peers, in the RTI Connext DDS Getting Started Guide.

To run rtiddsspy on a target system (not your host development platform), you must first select the target architecture. To do so, either:

  • Set the environment variable CONNEXTDDS_ARCH to the name of the target architecture. (Do this for each command shell you will be using.)

  • Or set the variable connextdds_architecture in the file rticommon_config.[sh/bat] to the name of the target architecture. (The file is resource/scripts/rticommon_config.sh on Linux® or macOS® systems, resource/scripts/rticommon_config.bat on Windows systems.) If the CONNEXTDDS_ARCH environment variable is set, the architecture in this file will be ignored.

Note

If you have more than one DataWriter for the same Topic, and these DataWriters have different settings for the Ownership QoS, then rtiddsspy will only receive (and thus report on) the samples from the first DataWriter.

Generic Options

-help

Prints a help message and exits.

Example: rtiddsspy -help

-version

Prints the version and exits.

Example: rtiddsspy -version

-domainId <NN>

Sets the domain ID. The valid range is 0 to 100.

Example: rtiddsspy -domainId 31

-domainTag <TAG>

Sets the domain tag. This is a string value with a maximum of 255 characters.

Example: rtiddsspy -domainTag "ENG. DEPT"

-index <NN>

Sets the participantIndex. If participantIndex is not -1 (auto), it must be different than the one used by all other applications in the same computer and domainId. If this is not respected, rtiddsspy (or the application that starts last) will get an initialization error.

Example: rtiddsspy -index 2

-appId <ID>

Sets the application ID. If unspecified, the system will pick one automatically. This option is rarely used.

Example: rtiddsspy -appId 34556

-verbosity <NN>

Sets the verbosity level. The range is 0 to 5.

  • 0 has minimal output and does not echo the fact that data is being sent or received.

  • 1 prints the most relevant statuses, including the sending and receiving of data. This is the default.

  • 2 prints a summary of the parameters being used and echoes more detailed status messages.

3-5 mostly affects the verbosity used by the internal DDS modules that implement rtiddsspy. The output is not always readable; its main purpose is to provide information that may be useful to RTI’s support team.

Example: rtiddsspy -verbosity 2

-peer <PEER>

Specifies a PEER to be used for discovery. Like any DDS application, it defaults to the setting of the environment variable NDDS_DISCOVERY_PEERS or a preconfigured multicast address if the environment is not set.

The format used for PEER is the same used for the NDDS_DISCOVERY_PEERS and is described in detail in Configuring the Peers List Used in Discovery. A brief summary follows:

The general format is: NN\@TRANSPORT://ADDRESS where:

  • ADDRESS is an address (in name form or using the IP notation xxx.xxx.xxx.xxx). ADDRESS may be a multicast address. ADDRESS cannot be omitted if the -peer option is specified.

  • TRANSPORT represents the kind of transport to use and NN is the maximum participantIndex expected at that location. NN can be omitted and defaults to ‘4’.

  • Valid settings for TRANSPORT are ‘udpv4’ and ‘shmem’. The default setting if the transport is omitted is ‘udpv4’.

The -peer option may be repeated to specify multiple peers.

Example: rtiddsspy -peer 10.10.1.192 -peer mars -peer 4\@pluto

-discoveryTTL <TTL>

Sets the TTL (time-to-live) used for multicast discovery. If not specified, it defaults to the builtin DDS default.

The valid range is 0 to 255. The value ‘0’ limits multicast to the node itself (i.e., can only discover applications running on the same computer). The value ‘1’ limits multicast discovery to computers on the same subnet. Settings greater than 1 generally indicate the maximum number of routers that may be traversed (although some routers may be configured differently).

Example: rtiddsspy -discoveryTTL 16

-transport <MASK>

Specifies a bit-mask that sets the enabled builtin transports. If not specified, the default set of transports is used (UDPv4 + shmem).

The bit values are: 1=UDPv4, 2=shmem, 8=UDPv6.

Example: rtiddsspy -transport 1

-msgMaxSize <SIZE>

Configures the maximum message size allowed by the installed transports. This option is needed if you are using rtiddsspy to communicate with an application that has set these transport parameters to larger-than-default values.

Example: rtiddsspy -msgMaxSize 1024

-shmRcvSize <SIZE>

Increases the shared memory receive-buffer size. This is needed if you are using rtiddsspy to communicate with an application that has set these transport parameters to larger-than-default values.

Example: rtiddsspy -shmRcvSize 1024

-tcMaxSize <SIZE>

Configures the maximum size, in bytes, of a received type code.

Example: rtiddsspy -tcMaxSize 1024

-qosFile <file>

Allows you to specify additional QoS XML settings using url_profile. For more information on the syntax, see How to Load XML-Specified QoS Settings, in the RTI Connext DDS Core Libraries User’s Manual.

Example: rtiddsspy -qosFile /home/user/QoSProfileFile.xml

-qosProfile <lib::prof>

Specifies the library name and profile name to be used. Settings in the QoS Profile are superseded by command-line options that conflict with these settings. For example, the -deadline command-line option period supersedes the deadline period in the QoS Profile.

In addition, the DDS_OwnershipQosPolicyKind QoS setting is superseded by rtiddsspy. DDS_OwnershipQosPolicyKind is set to the ownership kind of the first discovered publication of the Topic, enabling rtiddsspy to match with the DataWriter. Subsequent DataWriters for the same Topic, but using a different ownership policy kind, will not be matched.

Example: rtiddsspy -qosProfile BuiltinQosLibExp:Generic.MinimalMemoryFootprint

Spy-Specific Options

-hOutput

Prints an explanation of the table in the output and then exits. (These explanations are also described in Understanding the Output.)

Example: rtiddsspy -hOutput

-mode <USER|DISC>

Chooses between printing discovery data or user data. See Discovery vs. User Modes.

  • USER: Only prints user data samples. Skips discovery events. Also sets -printSample by default.

  • DISC: Only prints discovery events. Skips user data samples.

By default, if you do not specify a mode, rtiddsspy prints both discovery events and user data samples.

Example: rtiddsspy -mode USER

-deadline <SS>

Sets the requested DEADLINE QoS for the subscriptions made by rtiddsspy.

Note that the deadline period should be equal to or greater than the publisher’s deadline period. If not, the QoS will be incompatible. If the QoS is incompatible, rtiddsspy will not receive updates from that publisher.

Each time a deadline is detected, rtiddsspy will print a message that indicates the number of deadlines received so far.

Example: rtiddsspy -deadline 3.5

-discoveryPlugins <SDP|SDP2>

Configures the built-in discovery plugin used by rtiddsspy.

  • SDP: Simple Participant Discovery Protocol and Simple Endpoint Discovery Protocol.

  • SDP2: Simple Participant Discovery Protocol 2.0 (SPDP2) and Simple Endpoint Discovery Protocol.

By default, SDP is used as the discovery plugin.

Example: rtiddsspy -discoveryPlugins SDP2

-timeFilter <SS>

Sets the TIME_BASED_FILTER QoS for the subscriptions made by rtiddsspy. This QoS causes DDS to filter out messages that are published at a rate faster than what the filter duration permits. For example, if the filter duration is 10 seconds, messages will be printed no faster than once every 10 seconds.

Example: rtiddsspy -timeFilter 10.0

-history <DEPTH>

Sets the HISTORY depth QoS for the subscriptions made by rtiddsspy.

This option may be relevant if the publisher has batching turned on, or if you are using the -useFirstPublicationQos option, which causes a reliable or durable subscription to be created.

Example: rtiddsspy -history 1

-participantPartition <PARTITION>

Adds a partition to the list of partition names in the DDS_DomainParticipant entity. This option can be repeated to indicate multiple partitions. The first occurrence of this parameter resets the default partition list.

Default: * (unless overwritten with -qosProfile option)

Example: rtiddsspy -participantPartition A

-useFirstPublicationQos

Sets the DDS_ReliabilityQosPolicyKind and DDS_DurabilityQosPolicyKind of the subscription based on the first discovered publication of the Topic.

See also -history and -qosProfile options.

Example: rtiddsspy -useFirstPublicationQos

-subscriberPartition <PARTITION>

Adds a partition to the list of partition names in the DDS_Subscriber entity. This option can be repeated to indicate multiple partitions. The first occurrence of this parameter resets the default partition list.

Default: * (unless overwritten with -qosProfile option)

Example: rtiddsspy -subscriberPartition A

-showHandle

Prints additional information about each sample received. The additional information is the instance_handle field in the SampleHeader, which can be used to distinguish among multiple instances of data objects published under the same Topic and type names.

Samples that share the Topic and type names and have the same instance_handle value, represent value updates to the same data object. Samples that share the Topic and type names but have different instance_handle values, represent different data objects.

This option causes rtiddsspy to print an explanation of updates to the values of different data objects.

Example: rtiddsspy -showHandle

-showSampleFlags

Adds one field with the active flags associated with each sample.

Example: rtiddsspy -showSampleFlags

-showSampleIdentity

Adds two fields with the sample identity and related sample identity associated with each sample.

Example: rtiddsspy -showSampleIdentity

-typeRegex <REGEX>

Subscribes only to types that match the REGEX regular expression. The regular expression follows the UNIX style fnmatch syntax.

When typing a regular expression to a command-line shell, some symbols may need to be escaped to avoid interpretation by the shell. In general, it is safest to include the expression in double quotes.

This option may be repeated to specify multiple Topic expressions.

Example: rtiddsspy -typeRegex "SensorArray*"

-topicRegex <REGEX>

Subscribes only to Topics that match the REGEX regular expression. The regular expression follows the UNIX style fnmatch syntax.

When typing a regular expression to a command-line shell, some symbols may need to be escaped to avoid interpretation by the shell. In general, it is safest to include the expression in double quotes.

This option may be repeated to specify multiple Topic expressions.

Example: rtiddsspy -topicRegex "Alarm*"

-typeWidth <WIDTH>

Sets the maximum width of the type name field in the output. For example, if you don’t have room to display the whole name, you could reduce the width. The valid range is 1 to 255.

Example: rtiddsspy -typeWidth 123

-topicWidth <WIDTH>

Sets the maximum width of the Topic name field in the output. For example, if you don’t have room to display the whole name, you could reduce the width. The valid range is 1 to 255.

Example: rtiddsspy -topicWidth 123

-printSample <PLAIN|COMPACT>

Prints the value of the received samples. See Sample Display Options.

  • PLAIN: Default. Pretty-prints sample information for best readability.

  • COMPACT: Prints sample information in a single line using a JSON format.

Example: rtiddsspy -printSample COMPACT

-showEntityName

Displays the entity name each time a sample is received.

Example: rtiddsspy -showEntityName

-showPartition

Displays the partitions to which an entity belongs each time a new entity is discovered and sample is received.

See PARTITION QosPolicy, in the RTI Connext DDS Core Libraries User’s Manual for more information.

Example: rtiddsspy -showPartition

QoS Settings

rtiddsspy is configured to discover as many entities as possible. To do so, an internal profile is defined, called InternalSpyLibrary::InternalSpyProfile. This is the default profile, unless a profile called DefaultSpyLibrary::DefaultSpyProfile is found.

You can use the command-line option -qosProfile to tell rtiddsspy to use a specific lib::profile instead of DefaultSpyLibrary::DefaultSpyProfile.

Like all the other DDS applications, rtiddsspy loads all the profiles specified using the environment variable NDDS_QOS_PROFILES or the file named USER_QOS_PROFILES found in the current working directory.

The QoS settings used internally are available in the file RTIDDSSPY_QOS_PROFILES.example.xml.

Usage Examples for Linux and Windows Systems

On Linux, Windows, and other operating systems that have a shell, the syntax matches the regular commands available in the shell. (In the examples below, the string shell prompt> represents the prompt that the shell prints and is not part of the command that must be typed.)

shell prompt>  rtiddsspy -domainId 3
shell prompt>  rtiddsspy -domainId 5 -topicRegex "Alarm*"
shell prompt>  rtiddsspy -help

Usage Examples for VxWorks Systems

On VxWorks® systems, the libraries libnddscore.so, libnddsc.so, and libnddscpp.so must first be loaded.

The rtiddsspy command must be typed into the VxWorks shell (either an rlogin shell, a target-server shell, or the serial line prompt). The arguments are passed embedded into a single string, but otherwise have the same syntax as Windows systems. On Linux, Windows, and other operating systems that have a shell, the syntax matches the regular commands available in the shell. (In the examples below, the string vxworks prompt> represents the prompt that the shell prints and is not part of the command that must be typed.)

rtiddsspy "[<options>]"
Example: rtiddsspy "-domainId 3 -topicRegex Alarm*"

rtiddsspy requires about 25 kB of stack. If the stack size of the shell from which it is invoked is not large enough, use taskSpawn:

taskSpawn <name>, <priority>, <taskspawn options>, <stack size in bytes>, rtiddsspy, "[<options>]"

The options use the same syntax as above. For example:

taskSpawn "rtiddsspy", 100, 0x8, 50000, rtiddsspy, "-domainId 3 -topicRegex Alarm*"