|
RTI Connext C API
Version 6.1.0
|
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.
To run rtiddsspy on a target system (not your host development platform), you must first select the target architecture. To do so, either:
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
[-qosFile <file>]
[-qosProfile <lib::prof>] [-hOutput]
[-deadline <SS>] ... defaults to -1 (no deadline)
[-timeFilter <SS>] ... defaults to 0 (no filter)
[-history <DEPTH>] ... defaults to 8192
[-partition <partition>] ... defaults to *
[-useFirstPublicationQos]
[-showHandle]
[-showSampleIdentity]
[-typeRegex <REGEX>] ... defaults to "*"
[-topicRegex <REGEX>] ... defaults to "*"
[-typeWidth <WIDTH>] ... can be 1..255
[-topicWidth <WIDTH>] ... can be 1..255
[-truncate]
[-printSample]
[-use43LargeDataForm]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*"
Generic Options:
-help Prints a help message and exits.
-version Prints the version and exits.
-domainId <NN>
Sets the domain ID. The valid range is 0 to 100.
Example: rtiddsspy -domainId 31
-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 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
-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:
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.
-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.
Spy-Specific Options:
-hOutput
This option prints an explanation of the table in the output and then exits. For details, see the section below on Understanding the Output.
Example: rtiddsspy -hOutput
-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
-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
-partition <PARTITION>
Adds a partition to the list of partition names. 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)
-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
-showSampleIdentity
Add two columns with the sample identity and replated sample identity associated with each sample.
-typeRegex <REGEX>
Subscribe 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>
Subscribe 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 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.
use43LargeDataForm
Use this option if compatibility with RTI Data Distribution Service 4.3 is required and fragmented data is sent. This is the same as setting the corresponding properties in the PropertyQosPolicy.
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 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 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 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 "-domainId 3" vxworks prompt> rtiddsspy "-domainId 5 5 -topicRegex "Alarm*" vxworks prompt> rtiddsspy "-help"
Understanding the Output
This section provides the same information as the -hOutput option.
rtiddsspy's output is formatted as a table with the following columns:
source_timestamp Info Src HostId topic type ----------------- ---- ------------ ------------------ -----------------
There is an additional column 'Object GUID/Key' that can be enabled using the -showHandle option
There are two additional columns 'Sample Identity' and 'Related Sample ID entity' that can be enabled using the -showSampleIdentity option
The columns are described below:
source_timestamp
Contains the timestamp that appears in the SampleInfo associated with each sample. This timestamp represents the source-time when the sample was generated.
Src HostId
Contains the sourceId part of the Global Unique IDentifier (GUID) of the writer that sent the sample. This value is formatted as an IP address because this is the default setting for NDDS. Consequently this column will match the IP address of the sender of the message provided that:
(1) the application is running on an IP network,
(2) it has not disabled the UDPv4 transport and
(3) it has not explicitly overridden the 'appId'
Topic
The topic name. For discovery messages it refers to the topic that has been discovered. The width of this column can be configured using the -topicWidth <width> option.
Type
The type name. For discovery messages it refers to the type of the topic that has been discovered. The width of this column can be configured using the -typeWidth <width> option.
Object GUID/Key
This column is disabled by default. To enable it, use '-showHandle'. The column contains the 12 byte instance handle that appears in the SampleInfo associated with each sample.
Note that the information is only displayed for topics that have a key.
Note also that for simple key formats that can fit in 12 bytes it will exactly match the key.
Sample Identity
This column is disabled by default. To enable it, use '-showSampleIdentity'. The column contains the original publication virtual GUID and the original publication virtual sequence number that appears in the SampleInfo associated with each sample.
Related Sample Identity
This column is disabled by default. To enable it, use '-showSampleIdentity'. The column contains the related original publication virtual guid and the related original publication virtual sequence number that appears in the SampleInfo associated with each sample.
Info
The output is formatted as: A sB
where:
A – can take tha values 'W' 'R' 'D' 'd'
s – can take the values '+' '-' '?'
B – can take the values 'N' 'M'
The value of A distinguishes between discovery traffic and user traffic.
A = 'W' indicates discovery traffic and further means that nddsspy found a Writer described by the remaining columns
A = 'R' indicates discovery traffic and further means that nddsspy found a Reader described by the remaining columns
A = 'D' indicates a user-data message for a topic that has a key
A = 'd' indicates a user-data message for a topic that has no keys
s = '+' indicates that the instance state is 'ALIVE'. In the situation where A is 'W' or 'R', it indicates that the Writer or Reader are still considered alive.
s = '-' indicates that the instance state is 'NOT_ALIVE_DISPOSED'. If A is either 'W' or 'R', it means that the entity was explicitly deleted by the remote application.
s = '?' indicates that the instance state is 'NOT_ALIVE_NO_WRITERS'. If A is either 'W' or 'R' it means that the entity is considered to have died or is otherwise lost. This is usually seen if the application was killed or otherwise terminated without deleting entities and cleaning before shutting down
B = 'N' Indicates that the view_state in the SampleInfo is 'new'. This means that nddsspy had never seen the instance before.
B = 'M' Indicates that the view_state in the SampleInfo is 'modified'. This means that nddsspy had seen the instance before.