Usage

rtiddsping
      [-help]
      [-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
      [-discoveryPlugins <SDP|SDP2>]   ... defaults to SDP
      [-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>]
      [-reliable]                  ... defaults to best-efforts
      [-queueSize  <NN>]         ... defaults to 1
      [-durability <TYPE>]       ... TYPE can be VOLATILE or TRANSIENT_LOCAL
      [-topicName  <NAME>]       ... defaults to PingTopic
      [-typeName   <NAME>]       ... defaults to PingType
      [-useKeys    <NN>]         ... defaults to PingType
      [-publisher]                 ... this is the default
      [-sendPeriod <SS>]         ... SS is in seconds, defaults to 1
      [-numSamples <NN>]         ... defaults to infinite
      [-subscriber]                ... receive ping data
      [-multicast  <ADDRESS>]    ... defaults to no multicast
      [-timeout    <SS>]         ... SS is in seconds, defaults to infinite
      [-deadline   <SS>]         ... defaults to -1 (no deadline)
      [-timeFilter <SS>]         ... defaults to  0 (no filter)

Example:

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

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

Example: rtiddsping -domainId 31

-domainTag <TAG>

Sets the domain tag. This is a string value with a maximum of 255 characters.

Example: rtiddsping -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, rtiddsping (or the application that starts last) will get an initialization error.

Example: rtiddsping -index 2

-appId <ID>

Sets the application ID. If unspecified, the system will pick one automatically. This option is rarely used.

Example: rtiddsping -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 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

-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: rtiddsping -participantPartition A

-peer <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 Configuring the Peers List Used in Discovery, in the RTI Connext DDS Core Libraries User’s Manual. 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

-discoveryPlugins <SDP|SDP2>

Configures the built-in discovery plugin used by rtiddsping.

  • 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: rtiddsping -discoveryPlugins SDP2

-discoveryTTL <TTL>

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

Example: rtiddsping -transport 1

-msgMaxSize <SIZE>

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

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

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

Example: rtiddsping -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 DDS Core Libraries User’s Manual.

Example: rtiddsping -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.

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

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

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

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

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

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

Sets the period (in seconds) at which rtiddsping sends the messages.

Example: rtiddsping -sendPeriod 0.5

-numSamples <NN>

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

This option only applies if the -subscriber option is also specified.

Configures ping to receive messages over multicast. The <ADDRESS> 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 <SS>

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

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

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

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

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

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"