The WIRE_PROTOCOL QosPolicy configures some global Real-Time Publish Subscribe (RTPS) protocol-related properties for the DomainParticipant. The RTPS OMG-standard, interoperability protocol is used by Connext DDS to format and interpret messages between DomainParticipants.
It includes the members in . For defaults and valid ranges, please refer to the API Reference HTML documentation. (The default values contain the correctly initialized wire protocol attributes. They should not be modified without an understanding of the underlying Real-Time Publish Subscribe (RTPS) wire protocol.)
Type |
Field Name |
Description |
DDS_Long |
Unique identifier for participants that belong to the same DDS domain on the same host. See Choosing Participant IDs. |
|
DDS_UnsignedLong |
A machine/OS-specific host ID, unique in the DDS domain. See Host, App, and Instance IDs. |
|
A participant-specific ID, unique within the scope of the rtps_host_id. See Host, App, and Instance IDs. |
||
An instance-specific ID of the DomainParticipant that, together with the rtps_app_id, is unique within the scope of the rtps_host_id. See Host, App, and Instance IDs. |
||
DDS_RtpsWellKnownPorts_t |
Determines the well-known multicast and unicast ports for discovery and user traffic. See Ports Used for Discovery. |
|
DDS_RtpsReservedPortKindMask |
Specifies which well-known multicast and unicast ports to reserve when enabling the DomainParticipant. |
|
DDS_WireProtocolQosPolicyAutoKind |
Kind of auto mechanism used to calculate the GUID prefix. |
Note that DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) and DATA_READER_PROTOCOL QosPolicy (DDS Extension) configure RTPS and reliability properties on a per DataWriter and DataReader basis.
When you create a DomainParticipant, you must specify a domain ID, which identifies the communication channel across the whole system. Each DomainParticipant in the same DDS domain on the same host also needs a unique integer, known as the participant_id.
The participant_id uniquely identifies a DomainParticipant from other DomainParticipants in the same DDS domain on the same host. You can use the same participant_id value for DomainParticipants in the same DDS domain but running on different hosts.
The participant_id is also used to calculate the default unicast user-traffic and the unicast meta-traffic port numbers, as described in Ports Used for Discovery. If you only have one DomainParticipant in the same DDS domain on the same host, you will not need to modify this value.
You can either allow Connext DDS to select a participant ID automatically (by setting participant_id to -1), or choose a specific participant ID (by setting participant_id to the desired value).
The default value of participant_id is -1, which means Connext DDS will select a participant ID for you.
Connext DDS will pick the smallest participant ID, based on the unicast ports available on the transports enabled for discovery, based on the unicast and/or multicast ports available on the transports enabled for discovery and/or user traffic.
The rtps_reserved_ports_mask field determines which ports to check when picking the next available participant ID. The reserved ports are calculated based on the formula specified in Inbound Ports for Meta-Traffic an Inbound Ports for User Traffic. By default, Connext DDS will reserve the meta-traffic unicast port, the meta-traffic multicast port, and the user traffic unicast port.
Connext DDS will attempt to resolve an automatic port ID either when a DomainParticipant is enabled, or when a DataReader or a DataWriter is created. Therefore, all the transports enabled for discovery must have been registered by this time. Otherwise, the discovery transports registered after resolving the automatic port index may produce port conflicts when the DomainParticipant is enabled.
To see what value Connext DDS has selected, either:
If you do have multiple DomainParticipants on the same host, you should use consecutively numbered participant indices start from 0. This will make it easier to specify the discovery peers using the initial_peers parameter of this QosPolicy or the NDDS_DISCOVERY_PEERS environment variable. See Configuring the Peers List Used in Discovery for more information.
Do not use random participant indices since this would make DISCOVERY incredibly difficult to configure. In addition, the participant_id has a maximum value of 120 (and will be less for domain IDs other than 0) when using an IP-based transport since the participant_id is used to create the port number (see Ports Used for Discovery), and for IP, a port number cannot be larger than 65536.
For details, see Ports Used for Discovery.
The rtps_host_id, rtps_app_id, and rtps_instance_id values are used by the RTPS protocol to allow Connext DDS to distinguish messages received from different DomainParticipants. Their combined values must be globally unique across all existing DomainParticipants in the same DDS domain. In addition, if an application dies unexpectedly and is restarted, the IDs used by the new instance of DomainParticipants should be different than the ones used by the previous instances. A change in these values allows other DomainParticipants to know that they are communicating with a new instance of an application, and not the previous instance.
If the value of rtps_host_id is set to DDS_RTPS_AUTO_ID, the IPv4 address of the host is used as the host ID. If the host does not have an IPv4 address, the host-id will be automatically set to 0x7F000001.
If the value of rtps_app_id is set to DDS_RTPS_AUTO_ID, the process (or task) ID is used. There can be at most 256 distinct participants in a shared address space (process) with a unique rtps_app_id.
If the value of rtps_instance_id is set to DDS_RTPS_AUTO_ID, a counter is assigned that is incremented per new participant. Thus, together with rtps_app_id, there can be at most 2^64 distinct participants in a shared address space with a unique RTPS Globally Unique Identifier (GUID).
The rtps_well_known_ports structure allows you to configure the ports that are used for discovery of inbound meta-traffic (discovery data internal to Connext DDS) and user traffic (from your application).
It includes the members in . For defaults and valid ranges, please refer to the API Reference HTML documentation.
Type |
Field Name |
Description |
DDS_Long |
port_base |
The base port offset. All mapped well-known ports are offset by this value. Resulting ports must be within the range imposed by the underlying transport. |
domain_id_gain |
Tunable gain parameters. See Ports Used for Discovery. |
|
participant_id_gain |
||
builtin_multicast_port_offset |
Additional offset for meta-traffic port. See Inbound Ports for Meta-Traffic. |
|
builtin_unicast_port_offset |
||
user_multicast_port_offset |
Additional offset for user traffic port. See Inbound Ports for User Traffic. |
|
user_unicast_port_offset |
In order for the discovery process to work correctly, each DomainParticipant must have a unique identifier. This QoS policy specifies how that identifier should be generated.
RTPS defines a 96-bit prefix to this identifier; each DomainParticipant must have a unique value of this prefix relative to all other participants in its DDS domain. In order to make it easier to control how this 96-bit value is generated, Connext DDS divides it into three integers: a host ID, the value of which is based on the identity of the machine on which the participant is executing, an application ID (whose value is based on the process or task in which the participant is contained), and an instance ID which identifies the participant itself.
This QoS policy provides you with a choice of algorithms for generating these values automatically. In case none of these algorithms suit your needs, you may also choose to specify some or all of them yourself.
The following three fields compose the GUID prefix and by default are set to DDS_RTPS_AUTO_ID. The meaning of this flag depends on the value assigned to rtps_auto_id_kind.
Depending on the rtps_auto_id_kind value, there are three different scenarios:
Note: If the IP address assigned to the interface is not unique within the network (for instance, if it is not configured), then is it possible that the GUID (specifically, the rtps_host_id portion) may also not be unique.
Note to Solaris Users: To use DDS_RTPS_AUTO_ID_FROM_MAC, you must run the Connext DDS application while logged in as ‘root.’
Using DDS_RTPS_AUTO_ID_FROM_MAC, the default value of each field is interpreted as follows:
If DDS_RTPS_AUTO_ID_FROM_MAC is used, the rtps_instance_id has been logically split into two parts: 24 bits for the process/task ID and 8 bits for the per new participant counter. To give to users the ability to manually set the two parts independently, a bit field mechanism has been introduced for the rtps_instance_id field when it is used in combination with DDS_RTPS_AUTO_ID_FROM_MAC. If one of the two parts is set to 0, only this part will be handled by Connext DDS and you will be able to handle the other one manually.
Note: RTPS_AUTO_ID_FROM_UUID is only supported on iOS architectures.
Some examples are provided to better explain the behavior of this QoSPolicy in case you want to change the default behavior with DDS_RTPS_AUTO_ID_FROM_MAC.
DDS_DomainParticipantFactory_get_default_participant_qos( DDS_DomainParticipantFactory_get_instance(), &participant_qos);
participant_qos.wire_protocol.rtps_auto_id_kind =
DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id =
(/* App ID */ (12 << 8) | /* Instance ID*/ (DDS_RTPS_AUTO_ID));
participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id =
(/* App ID */ (DDS_RTPS_AUTO_ID) | /* Instance ID*/ (12));
participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id =
( /* App ID */ (12 << 8)) | /* Instance ID */ (9) )
Note: If you are using DDS_RTPS_AUTO_ID_FROM_MAC as rtps_auto_id_kind and you decide to manually handle the rtps_instance_id field, you must ensure that both parts are non-zero (otherwise Connext DDS will take responsibility for them).
RTI recommends that you always specify the two parts separately in order to avoid errors.
participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id = DDS_RTPS_AUTO_ID;
Note: If you are using DDS_RTPS_AUTO_ID_FROM_MAC as rtps_auto_id_kind and you decide to manually set the rtps_instance_id field, you must ensure that both parts are non-zero (otherwise Connext DDS will take responsibility for them). RTI recommends that you always specify the two parts separately in order to clearly show the difference.
On many real-time operating systems, and even on some non-real-time operating systems, when a node is rebooted, and applications are automatically started, process ids are deterministically assigned. That is, when the system restarts or if an application dies and is restarted, the application will be reassigned the same process or task ID.
This means that Connext DDS’s automatic algorithm for creating unique rtps_app_id’s will produce the same value between sequential instances of the same application. This will confuse the other DomainParticipants on the network into thinking that they are communicating with the previous instance of the application instead of a new instance. Errors usually resulting in a failure to communicate will ensue.
Thus for applications running on nodes that may be rebooted without letting the application shutdown appropriately (destroying the DomainParticipant), especially on nodes running real-time operating systems like VxWorks or LynxOS, you will want to set the rtps_app_id manually. We suggest that a strictly incrementing counter is stored either on a file system or in non-volatile RAM is used for the rtps_app_id.
Whatever method you use, you should make sure that the rtps_app_id is unique across all DomainParticipants running on a host as well as DomainParticipants that were recently running on the host. After a period configured through the DISCOVERY_CONFIG QosPolicy existing applications will eventually flush old DomainParticipants that did not properly shutdown from their databases. When that is done, then rtps_app_id may be reused.
This QosPolicy cannot be modified after the DomainParticipant is created.
If manually set, it must be set differently for every DomainParticipant in the same DDS domain across all applications. The value of rtps_app_id should also change between different invocations of the same application (for example, when an application is restarted).
The use of this policy does not significantly impact the use of resources.
© 2016 RTI