Usage

Getting Started with DDS Spy

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 "udpv4|shmem"
      [-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
      [-timeFormat <SHORT|FULL|EPOCH>]    ... default SHORT
      [-showEntityName]
      [-showPartition]
      [-showTypeDefinition]
      [-typeDefinitionFormat <IDL|XML>]   ... defaults to IDL
      [-showSampleSchema]
      [-showEntityQos]
      [-srcLocators <MASK>]               ... defaults to "udpv4"

Examples:

  • By default, rtiddsspy displays all topics and entities observed on domain 0:

    rtiddsspy

  • Use domain ID 3 and also print the data for all Topics:

    rtiddsspy -domainId 3 -printSample

  • Specify a subset of Topics to display:

    rtiddsspy -domainId 3 -topicRegex "Alarm*"

rtiddsspy uses the same discovery mechanism as any other DDS application. If your applications run on a network without multicast support, you may have to set the initial discovery peers. You can do that with the -peer option. For more information, see the Generic Options section below and How do I set my discovery peers? in the Connext Getting Started Guide.

rtiddsspy is provided for both the host platform and, for certain architectures, the target platform. By default, rtiddsspy runs for the host platform (located in resource/app/bin/<host>). To configure the script to run rtiddsspy for a target platform (located in resource/app/bin/<target>), specify the target architecture in either of the following variables (these instructions do not apply to embedded systems; for those, see Usage Examples for Embedded Systems):

  • The environment variable CONNEXTDDS_ARCH.

  • The variable connextdds_architecture in the file rticommon_config.[sh/bat]. (The file is resource/scripts/rticommon_config.sh on Linux or macOS systems, resource/scripts/rticommon_config.bat on Windows systems.)

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. The domain ID cannot be set using an XML configuration file. To successfully specify the domain ID, you must use the domainID option.

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 mask that sets the enabled builtin transports.

Values: udpv4, shmem, udpv6, udpv4_wan or a combination of them separated by |.

Default: "udpv4|shmem".

When combining multiple values with |, the mask must be enclosed in double quotes.

Example: rtiddsspy -transport "udpv4|shmem"

-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 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

For discovery events, this option prints the GUID of the discovered entity (DataWriter or DataReader) and the object ID of its parent entity (Publisher or Subscriber).

For user data samples events, this option prints the instance_handle field in the SampleHeader, which can be used to distinguish among multiple instances of data objects published under the same Topic.

Samples that share the Topic and have the same instance_handle value represent value updates to the same data object.

Samples that share the Topic but have different instance_handle values represent different data objects.

This option is automatically enabled when using the -mode DISC option.

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.

The JSON schema for the printed samples can be displayed using the -showSampleSchema option. There may be more than one schema if multiple types are being discovered.

Example: rtiddsspy -printSample COMPACT

-timeFormat <SHORT|FULL|EPOCH>

Sets the format for timestamps

  • SHORT: Default. hh:mm:ss.

  • FULL: yyyy-mm-dd hh:mm:ss.s.

  • EPOCH: Seconds since the UNIX epoch.

Example: rtiddsspy -timeFormat FULL

-showEntityName

Displays the entity name each time a sample is received.

This option is automatically enabled when using the -mode DISC option.

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 Core Libraries User’s Manual for more information.

This option is automatically enabled when using the -mode DISC option.

Example: rtiddsspy -showPartition

-showTypeDefinition

Displays the type definition each time a new remote endpoint with type information is discovered.

The type definition is useful for understanding the structure of the type associated with the remote endpoint.

In addition to the type definition, this option reveals the completeTypeHash and minimalTypeHash values associated with the type. These values represent the two forms of equivalence hash, “complete” and “minimal”, as defined in the DDS-XTypes specification for aggregate types.

Example: rtiddsspy -showTypeDefinition

-typeDefinitionFormat <IDL|XML>

Specifies the format used to display the type definition when using the -showTypeDefinition option.

Values: IDL, XML

Default: IDL

Example: rtiddsspy -showTypeDefinition -typeDefinitionFormat XML

-showSampleSchema

Displays the sample JSON Schema each time a new remote endpoint with type information is discovered.

In addition to the type definition, this option reveals the completeTypeHash and minimalTypeHash values associated with the type. These values represent the two forms of equivalence hash, “complete” and “minimal”, as defined in the DDS-XTypes specification for aggregate types.

The JSON Schema is useful for understanding the structure of the data samples being received. These samples can be printed in JSON format using the -printSample COMPACT option.

It is important to note that the generated JSON Schema describes the structure of JSON data samples for a given type. It is not intended to be a complete or canonical representation of an IDL type. To obtain a complete representation of an IDL type, use the -showTypeDefinition option, which provides the full IDL definition of the type.

Example: rtiddsspy -showSampleSchema

-showEntityQos

Displays the entity QoS policies that affect matching each time a new entity is discovered.

The displayed QoS policies are:

  • Reliability

  • Durability

  • Deadline

  • Destination Order

  • Ownership

  • Data Representation

  • Latency Budget

  • Liveliness

  • Partition

  • Presentation

Example: rtiddsspy -showEntityQos

-srcLocators <MASK>

Specifies which source locators to display.

Values: udpv4, shmem, udpv6, udpv4_wan or a combination of them separated by |.

Default: udpv4.

When combining multiple values with |, the mask must be enclosed in double quotes.

See Source Locators in Default Output for more information.

Example: rtiddsspy -srcLocators "udpv4|shmem"

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 Host 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 Embedded Systems

On embedded systems such as VxWorks®, the libraries libnddscore.so, libnddsc.so, and libnddscpp.so must first be loaded. See the “Building and Running” section for your platform in the Getting Started Guide Addendum for Embedded Systems. Follow the instructions for loading and running your application. (The rtiddsspy application is already compiled; you do not need to compile it.) Copy rtiddsspy from resource/app/bin/<target_architecture>/rtiddsspy to your target platform.

The rtiddsspy command must be typed into the 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.)

vxworks prompt> 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:

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

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

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