Sends or receives simple messages using RTI Connext. More...

Sends or receives simple messages using RTI Connext.

The rtiddsping utility uses RTI Connext to send and receive preconfigured "Ping" messages to other rtiddsping applications which can be running in the same or different computers.

The rtiddsping utility can used to test the network and/or computer configuration and the environment settings that affect the operation of RTI Connext.

Note: To run rtiddsping 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.

Usage

  rtiddsping [-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>]

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

VxWorks Usage

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

  Example: rtiddsping "-domainId 3 -publisher -numSamples 100"

  If the stack of the shell is not large enough to run rtiddsping, use "taskSpawn":

  taskSpawn <name>,<priority>,<taskspawn options>,<stack size in bytes>,rtiddsping,"[\<options\>]"
        The options use the same syntax as above.

  Example taskSpawn "rtiddsping",100,0x8,50000,rtiddsping,"-domainId 3 -publisher -numSamples 100"

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: rtiddsping -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, 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 that are in use and echoes more detailed status messages.

3-5 Mostly affects the verbosity used by the internal RTI Connext 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 <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 one used for 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: rtiddsping -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. Values higher 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>

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>

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

-shmRcvSize <SIZE>

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

-tcMaxSize <SIZE>

Set the maximum size (in bytes) for a type code.

-qosFile <file>

Allow 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: rtiddsping -qosFile /home/user/QoSProfileFile.xml

-qosProfile <lib::prof>

This option specifies the library name and profile name that the tool should use.

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 maximal number of samples to hold in the queue. In the case of the publisher, it 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 stablished.

Example: rtiddsping -useKeys 20

Ping Publishing Options:

-publisher

Causes rtiddsping to send ping messages. This 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. messages.

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>

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

Sets the DEADLINE QoS for the subscriptions made by rtiddsping.

Note that the deadline period should be smaller than the publisher's sendPeriod. 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 indicating the number of deadlines received so far.

Example: rtiddsping -deadline 3.5

-timeFilter <SS>

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

Sets the TIME_BASED_FILTER QoS for the subscriptions made by rtiddsping. 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 every 10 seconds.

Example: rtiddsping -timeFilter 5.5

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

Description

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

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>  rtiddsping -domainId 3 -publisher -numSamples 100
shell prompt>  rtiddsping -domainId 5 -subscriber -timeout 20
shell prompt>  rtiddsping -help

VxWorks examples:

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 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 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 '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"

or, 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"