.. include:: vars.rst Usage ***** .. code-block:: bash rtiddsspy [-help] [-version] [-domainId ] ... defaults to 0 [-index ] ... defaults to -1 (auto) [-appId ] ... defaults to a middleware-selected value [-verbosity ] ... can be 0..5 [-peer ] ... PEER format is NN\@TRANSPORT://ADDRESS [-discoveryTTL ] ... can be 0..255 [-transport ] ... defaults to DDS_TRANSPORTBUILTIN_MASK_DEFAULT [-msgMaxSize ] ... defaults to -1 (transport default) [-shmRcvSize ] ... defaults to -1 (transport default) [-tcMaxSize ] ... defaults to 4096 [-qosFile ] [-qosProfile ] [-hOutput] [-mode ] [-deadline ] ... defaults to -1 (no deadline) [-timeFilter ] ... defaults to 0 (no filter) [-history ] ... defaults to 8192 [-partition ] ... defaults to * [-useFirstPublicationQos] [-showHandle] [-showSampleIdentity] [-typeRegex ] ... defaults to "*" [-topicRegex ] ... defaults to "*" [-typeWidth ] ... can be 1..255 [-topicWidth ] ... can be 1..255 [-printSample ] ... default PLAIN [-showEntityName] [-showPartition] Example: .. code-block:: bash 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 :link_connext_dds_pro_gsg_cpp11:`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 Sets the domain ID. The valid range is 0 to 100. Example: ``rtiddsspy -domainId 31`` -index 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 Sets the application ID. If unspecified, the system will pick one automatically. This option is rarely used. Example: ``rtiddsspy -appId 34556`` -verbosity 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 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 :link_connext_dds_pro_um:`Configuring the Peers List Used in Discovery <#users_manual/ConfigPeersListUsed_inDiscov.htm>`. 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 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 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 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 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 Configures the maximum size, in bytes, of a received type code. Example: ``rtiddsspy -tcMaxSize 1024`` -qosFile Allows you to specify additional QoS XML settings using **url_profile**. For more information on the syntax, see :link_connext_dds_pro_um:`How to Load XML-Specified QoS Settings, in the RTI Connext DDS Core Libraries User's Manual <#users_manual/How_to_Load_XML_Specified_QoS_Settings.htm>`. Example: ``rtiddsspy -qosFile /home/user/QoSProfileFile.xml`` -qosProfile Specifies the library name and profile name to be used. Example: ``rtiddsspy -qosProfile BuiltinQosLibExp:Generic.MinimalMemoryFootprint`` .. _spy-specific-options: Spy-Specific Options ==================== -hOutput Prints an explanation of the table in the output and then exits. (These explanations are also described in :ref:`understand-spy-output`.) Example: ``rtiddsspy -hOutput`` -mode Chooses between printing discovery data or user data. See :ref:`spy-mode`. * 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 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 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 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`` -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) Example: ``rtiddsspy -partition A`` -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 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`` -showSampleIdentity Adds two fields with the sample identity and related sample identity associated with each sample. Example: ``rtiddsspy -showSampleIdentity`` -typeRegex 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 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 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 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 Prints the value of the received samples. See :ref:`spy-print-mode`. * 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 :link_connext_dds_pro_um:`PARTITION QosPolicy, in the RTI Connext DDS Core Libraries User's Manual <#users_manual/PARTITION_QosPolicy.htm>` 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.) .. code-block:: bash 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.) .. code-block:: bash rtiddsspy "[]" 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``: .. code-block:: bash taskSpawn , , , , rtiddsspy, "[]" The options use the same syntax as above. For example: .. code-block:: bash taskSpawn "rtiddsspy", 100, 0x8, 50000, rtiddsspy, "-domainId 3 -topicRegex Alarm*"