Debugging tool which receives all RTI Connext communication. More...

Debugging tool which receives all RTI Connext communication.

The rtiddsspy utility allows the user to monitor groups of publications available on any RTI Connext domain.

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.

To run rtiddsspy, like any RTI Connext application, you must have the NDDS_DISCOVERY_PEERS environment variable that defines your RTI Connext domain; otherwise you must specify the peers as command line parameters.

Usage

  rtiddsspy [-help] [-version] 
        [-domainId <domainId>]     ... defaults to 0
        [-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
        [-hOutput]            
        [-deadline   <SS>]         ... defaults to -1 (no deadline)
        [-history   <DEPTH>]       ... defaults to 8192
        [-timeFilter <SS>]         ... defaults to  0 (no filter)
        [-useFirstPublicationQos]         
        [-showHandle]         
        [-typeRegex <REGEX>]       ... defaults to "*"
        [-topicRegex <REGEX>]      ... defaults to "*"
        [-typeWidth <WIDTH>]       ... can be 1..255
        [-topicWidth <WIDTH>]      ... can be 1..255
        [-truncate]
        [-printSample]
        [-qosFile <file>]         
        [-qosProfile  <lib::prof>]

 Example: rtiddsspy -domainId 3 -topicRegex "Alarm*"

VxWorks Usage

  rtiddsspy "[<options>]"
        The options use the same syntax as above.

  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.

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

Options:

-help Prints a help message and exits.

-version Prints the version and exits.

-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 affect the verbosity used by the internal RTI Connext 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

-domainId <NN>

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

Example: rtiddsspy -domainId 31

-appId <ID>

Sets the application ID. If unspecified, the system will pick one automatically.

This option is rarely used.

Example: rtiddsspy -appId 34556

-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

-peer <PEER>

Specifies a PEER to be used for discovery. Like any RTI Connext 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 NDDS_DISCOVERY_PEERS. 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.
TRANSPORT represents the kind of transport to use and NN is the maximum participantIndex expected at that location. NN can be omitted and it is defaulted to '4'
Valid settings for TRANSPORT are 'udpv4' and 'shmem'. The default setting if the transport is omitted is 'udpv4'
ADDRESS cannot be omitted if the '-peer' option is specified.

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 built-in RTI Connext 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.

-msgMaxSize <SIZE>

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

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

-tcMaxSize <SIZE>

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

-hOutput

Prints information on the output format used by rtiddsspy.

This option prints an explanation of the output and then exits.

Example: rtiddsspy -hOutput

-deadline <SS>

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

Note that this may cause the subscription QoS to be incompatible with the publisher if the publisher did not specify an offered deadline that is greater or equal to the one requested by rtiddsspy. If the QoS is incompatible rtiddsspy will not receive updates from that writer.

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

-timeFilter <SS>

Sets the TIME_BASED_FILTER QoS for the subscriptions made by rtiddsspy. This QoS causes RTI Connext 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 each 10 seconds.

Example: rtiddsspy -timeFilter 10.0

-history <DEPTH>

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

This may be relevant if the publisher has batching turned on, or if the -useFirstPublicationQos option is used that is causing a reliable or durable subscription to be created.

Example: rtiddsspy -history 1

-useFirstPublicationQos

Sets the RELIABILITY and DURABILITY QoS of the subscription based on the first discovered publication of that topic.

See also -history option.

Example: rtiddsspy -useFirstPublicationQos

-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 displayed that share the topic and type names and also have the same value for the instance_handle represent value updates to the same data object. On the other hand, samples that share the topic and type names but display different values for the instance_handle.

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

Example: rtiddsspy -showHandle

-typeRegex <REGEX>

Subscribe only to types that match the REGEX regular expression. The syntax of the regular expression is defined by the POSIX regex function.

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>

Subscribe only to topics that match the REGEX regular expression. The syntax of the regular expression is defined by the POSIX regex function.

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 topic multiple expressions.

Example: rtiddsspy -topicRegex "Alarm*"

-typeWidth <WIDTH>

Sets the maximum width of the Type name column. Names wider than this will wrap around, unless -truncate is specified. Can be 1..255.

-topicWidth <WIDTH>

Sets the maximum width of the Topic name column. Names wider than this will wrap around, unless -truncate is specified. Can be 1..255.

-truncate

Specifies that names exceeding the maximum number of characters should be truncated.

-printSample

Prints the value of the received samples.

-qosFile <file>

Allows you to specify additional QoS XML settings using url_profile. For more information on the syntax, see Chapter 15 in the RTI Connext User's Manual.

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

-qosProfile <lib::prof>

Specifies the library name and profile name to be used.

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 speficied lib::profile instead of DefaultSpyLibrary::DefaultSpyProfile. Like all the other RTI Connext 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

The usage depends on the operating system from which rtiddsspy is executed.

Examples for UNIX, Linux, Windows systems

On UNIX, Linux, Windows and other operating systems that have a shell, the syntax matches the one of the regular commands available in the shell. In the examples below, the string 'shell prompt>' represents the prompt that the shell prints and are 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

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 to 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 for Unix/Windows. In UNIX, Linux, Windows and other operating systems that have a shell, the syntax matches the one of the regular comamnds available in the shell. In the examples below, the string 'vxworks prompt>' represents the prompt that the shell prints and are not part of the command that must be typed.

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