.. include:: vars.rst Usage ***** .. code-block:: bash rtiddsping [-help] [-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 ] [-reliable] ... defaults to best-efforts [-queueSize ] ... defaults to 1 [-durability ] ... TYPE can be VOLATILE or TRANSIENT_LOCAL [-topicName ] ... defaults to PingTopic [-typeName ] ... defaults to PingType [-useKeys ] ... defaults to PingType [-publisher] ... this is the default [-sendPeriod ] ... SS is in seconds, defaults to 1 [-numSamples ] ... defaults to infinite [-subscriber] ... receive ping data [-multicast
] ... defaults to no multicast [-timeout ] ... SS is in seconds, defaults to infinite [-deadline ] ... defaults to -1 (no deadline) [-timeFilter ] ... defaults to 0 (no filter) Example: .. code-block:: bash rtiddsping -domainId 3 -publisher -numSamples 100 Generic Options =============== -help Prints a help message and exits. Example: ``rtiddsping -help`` -version Prints the version and exits. Example: ``rtiddsping -version`` -domainId Sets the domain ID. The valid range is 0 to 100. Example: ``rtiddsping -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, *rtiddsping* (or the application that starts last) will get an initialization error. Example: ``rtiddsping -index 2`` -appId Sets the application ID. If unspecified, the system will pick one automatically. This option is rarely used. Example: ``rtiddsping -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 *rtiddsping*. The output is not always readable; its main purpose is to provide information that may be useful to RTI's support team. Example: ``rtiddsping -verbosity 2`` -peer Specifies a PEER to be used for discovery. Like any DDS application, this option 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 ``NDDS_DISCOVERY_PEERS`` and is described in detail in :link_connext_dds_pro_um:`Configuring the Peers List Used in Discovery, in the RTI Connext DDS Core Libraries User's Manual <#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: ``rtiddsping -peer 10.10.1.192 -peer mars -peer 4\@pluto`` -discoveryTTL Sets the TTL (time-to-live) used for multicast discovery. If not specified, this option 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: ``rtiddsping -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: ``rtiddsping -transport 1`` -msgMaxSize Configures the maximum message size allowed by the installed transports. This option is needed if you are using *rtiddsping* to communicate with an application that has set these transport parameters to larger-than-default values. Example: ``rtiddsping -msgMaxSize 1024`` -shmRcvSize Increases the shared memory receive-buffer size. This is needed if you are using *rtiddsping* to communicate with an application that has set these transport parameters to larger-than-default values. Example: ``rtiddsping -shmRcvSize 1024`` -tcMaxSize Configures the maximum size, in bytes, of a received type code. Example: ``rtiddsping -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: ``rtiddsping -qosFile /home/user/QoSProfileFile.xml`` -qosProfile Specifies the library name and profile name to be used. Example: ``rtiddsping -qosProfile BuiltinQosLibExp:Generic.MinimalMemoryFootprint`` Ping-Specific Options ===================== -reliable Configures the RELIABILITY QoS for publishing or subscribing. The default setting (if ``-reliable`` is not used) is ``BEST_EFFORT``. Example: ``rtiddsping -reliable`` -queueSize Specifies the maximum number of samples to hold in the queue. In the case of the publisher, this option affects the samples that are available for a late-joining subscriber. Example: ``rtiddsping -queueSize 100`` -durability Sets the DURABILITY QoS used for publishing or subscribing. Valid settings are: ``VOLATILE`` and ``TRANSIENT_LOCAL`` (default). The effect of this setting can only be observed when it is used in in conjunction with reliability and a queueSize larger than 1. If all these conditions are met, a late-joining subscriber will be able to see up to queueSize samples that were previously written by the publisher. Example: ``rtiddsping -durability VOLATILE`` -topicName Sets the *Topic* name used by *rtiddsping*. The default is ``RTIddsPingTopic``. To communicate, both the publisher and subscriber must specify the same *Topic* name. Example: ``rtiddsping -topicName Alarm`` -typeName Sets the type name used by *rtiddsping*. The default is ``RTIddsPingType``. To communicate, both publisher and subscriber must specify the same type name. Example: ``rtiddsping -typeName AlarmDescription`` -useKeys This option causes *rtiddsping* to use a *Topic* whose data contains a key. The value of the NN parameter indicates the number of different data objects (each identified by a different value of the key) that will be published by *rtiddsping*. The value of NN only affects the publishing behavior. However, NN still needs to be specified when the ``-useKeys`` option is used with the ``-subscriber`` option. For communication to occur, both the publisher and subscriber must agree on whether the *Topic* that they publish/subscribe contains a key. Consequently, if you specify the ``-useKeys`` parameter for the publisher, you must do the same with the subscriber. Otherwise, communication will not be established. Example: ``rtiddsping -useKeys 20`` Ping Publishing Options ======================= -publisher Causes *rtiddsping* to send ping messages. This option is the default. Example: ``rtiddsping -publisher`` -sendPeriod Sets the period (in seconds) at which *rtiddsping* sends the messages. Example: ``rtiddsping -sendPeriod 0.5`` -numSamples Sets the number of samples that will be sent by *rtiddsping*. After those samples are sent, *rtiddsping* will exit. Example: ``rtiddsping -numSamples 10`` Ping Subscribing Options ======================== -subscriber Causes *rtiddsping* to listen for ping messages. This option cannot be specified if ``-publisher`` is also specified. Example: ``rtiddsping -subscriber`` -multicast
This option only applies if the ``-subscriber`` option is also specified. Configures ping to receive messages over multicast. The ``
`` parameter indicates the address to use. ADDRESS must be in the valid range for multicast addresses. For IP version 4, the valid range is ``224.0.0.1`` to ``239.255.255.255``. Example: ``rtiddsping -multicast 225.1.1.1`` -timeout This option only applies if the ``-subscriber`` option is also specified. Sets a timeout (in seconds) that will cause *rtiddsping* to exit if no samples are received for a duration that exceeds the timeout. Example: ``rtiddsping -timeout 30`` -deadline Sets the requested DEADLINE QoS for the subscriptions made by *rtiddsping*. 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, *rtiddsping* will not receive updates from that publisher. Each time a deadline is detected, *rtiddsping* will print a message that indicates the number of deadlines received so far. Example: ``rtiddsping -deadline 3.5`` -timeFilter Sets the TIME_BASED_FILTER QoS for the subscriptions made by *rtiddsping*. 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: ``rtiddsping -timeFilter 10.0`` QoS Settings ============ *rtiddsping* is configured internally using a special set of QoS settings in a profile called ``InternalPingLibrary::InternalPingProfile``. This is the default profile unless a profile called ``DefaultPingLibrary::DefaultPingProfile`` is found. You can use the command-line option ``-qosProfile`` to tell *rtiddsping* to use a different ``lib::profile`` instead of ``DefaultPingLibrary::DefaultPingProfile``. Like all the other |CONNEXT| applications, *rtiddsping* 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 ``RTIDDSSPING_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 that of 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> rtiddsping -domainId 3 -publisher -numSamples 100 shell prompt> rtiddsping -domainId 5 -subscriber -timeout 20 shell prompt> rtiddsping -help Usage Examples for VxWorks Systems ================================== On VxWorks® systems, the libraries ``libnddscore.so``, ``libnddsc.so``, and ``libnddscpp.so`` must first be loaded. The *rtiddsping* command must be typed to the VxWorks shell (either a login 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 Linux/Windows. In Linux, Windows, and other operating systems that have a shell, the syntax matches that of 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 vxworks prompt> rtiddsping "-domainId 3 -publisher -numSamples 100" vxworks prompt> rtiddsping "-domainId 5 -subscriber -timeout 20" vxworks prompt> rtiddsping "-help" Alternatively (to avoid overflowing the stack): .. code-block:: bash vxworks prompt> taskSpawn "rtiddsping", 100, 0x8, 50000, rtiddsping, "-domainId 3 -publisher -numSamples 100" vxworks prompt> taskSpawn "rtiddsping", 100, 0x8, 50000, rtiddsping, "-domainId 5 -subscriber -timeout 20" vxworks prompt> taskSpawn "rtiddsping", 100, 0x8, 50000, rtiddsping, "-help"