WIRE_PROTOCOL QosPolicy (DDS Extension)

44.9 WIRE_PROTOCOL QosPolicy (DDS Extension)

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 to format and interpret messages between DomainParticipants.

It includes the members in Table 44.12 DDS_WireProtocolQosPolicy. 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.)

Table 44.12 DDS_WireProtocolQosPolicy
Type	Field Name	Description
DDS_Long	participant_id	Unique identifier for participants that belong to the same DDS domain on the same host. See 44.9.1 Choosing Participant IDs.
DDS_UnsignedLong	rtps_host_id	A machine/OS-specific host ID, unique in the DDS domain. See 44.9.3 Controlling How the GUID is Set (rtps_auto_id_kind).
	rtps_app_id	A participant-specific ID, unique within the scope of the rtps_host_id. See 44.9.3 Controlling How the GUID is Set (rtps_auto_id_kind).
	rtps_instance_id	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 44.9.3 Controlling How the GUID is Set (rtps_auto_id_kind).
DDS_RtpsWellKnownPorts_t	rtps_well_known _ports	Determines the well-known multicast and unicast ports for discovery and user traffic. See 44.9.2 Ports Used for Discovery.
DDS_RtpsReservedPortKindMask	rtps_reserved_ports _mask	Specifies which well-known multicast and unicast ports to reserve when enabling the DomainParticipant.
DDS_WireProtocolQosPolicyAutoKind	rtps_auto_id_kind	Kind of auto mechanism used to calculate the GUID prefix.
DDS_Boolean	compute_crc	Adds an RTPS CRC submessage to every message.
DDS_Boolean	check_crc	Checks if the received RTPS message is valid by comparing the computed CRC with the received RTPS CRC submessage.

Note that 47.5 DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) and 48.1 DATA_READER_PROTOCOL QosPolicy (DDS Extension) configure RTPS and reliability properties on a per DataWriter and DataReader basis.

44.9.1 Choosing Participant IDs

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

Automatic Participant ID Selection

The default value of participant_id is -1, which means Connext will select a participant ID for you.

Connext 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 23.1 Inbound Ports for Meta-Traffic an 23.2 Inbound Ports for User Traffic. By default, Connext will reserve the meta-traffic unicast port, the meta-traffic multicast port, and the user traffic unicast port.

Connext 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 has selected, either:

Change the verbosity level of the NDDS_CONFIG_LOG_CATEGORY_API category to NDDS_CONFIG_LOG_VERBOSITY_STATUS_LOCAL (see 54.2 Configuring Connext Logging).
Call get_qos() and look at the participant_id value in the 44.9 WIRE_PROTOCOL QosPolicy (DDS Extension) after the DomainParticipant is enabled.

Manual Participant ID Selection

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 24. 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 23. Ports Used for Discovery), and for IP, a port number cannot be larger than 65536.

For details, see 23. Ports Used for Discovery.

44.9.2 Ports Used for Discovery

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) and user traffic (from your application).

It includes the members in Table 44.13 DDS_RtpsWellKnownPorts_t. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 44.13 DDS_RtpsWellKnownPorts_t
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 23. Ports Used for Discovery.
	participant_id_gain	Tunable gain parameters. See 23. Ports Used for Discovery.
	builtin_multicast_port_offset	Additional offset for meta-traffic port. See 23.1 Inbound Ports for Meta-Traffic.
	builtin_unicast_port_offset
	user_multicast_port_offset	Additional offset for user traffic port. See 23.2 Inbound Ports for User Traffic.
	user_unicast_port_offset

44.9.3 Controlling How the GUID is Set (rtps_auto_id_kind)

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.

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.

For legacy reasons, Connext divides the 96-bit prefix into three integers:

The first integer is called host ID. The original purpose of this integer was to contain the identity of the machine on which the DomainParticipant is executing.
The second integer is called an application ID. The original purpose of this integer was to contain a value that identifies the process or task in which the DomainParticipant is contained.
The third integer is called instance ID. The original purpose was to contain a value that uniquely identifies a DomainParticipant within a task or process.

The rtps_auto_id_kind field can be used to configure the algorithm that Connext uses to populate the 96-bit prefix. Then you can optionally overwrite specific parts of the 96-bit prefix by explicitly configuring the rtps_host_id (first integer), rtps_app_id (second integer), and rtps_instance_id (third integer).

The rtps_auto_id_kind field supports three different prefix generation algorithms:

In the default and most common scenario, rtps_auto_id_kind is set to RTPS_AUTO_ID_FROM_UUID. As the name suggests, this mechanism uses a unique, randomly generated UUID to fill the rtps_host_id, rtps_app_id, or rtps_instance_id fields. The first two bytes of the rtps_host_id are replaced with the RTI vendor ID (0x0101).
(Legacy) When rtps_auto_id_kind is set to DDS_RTPS_AUTO_ID_FROM_IP, the 96-bit prefix is generated as follows:
- rtps_host_id: the 32 bit value of the IPv4 of the first up and running interface of the host machine is assigned. If the host does not have an IPv4 address, the host-id will be automatically set to 0x7F000001.
- rtps_app_id: the process (or task) ID is assigned.
- rtps_instance_id: A counter is assigned that is incremented per new participant within a process.
DDS_RTPS_AUTO_ID_FROM_IP is not a good algorithm to guarantee prefix uniqueness, because the process ID can be recycled by the OSs. See 44.9.3.2 Uniqueness Problem with DDS_RTPS_AUTO_ID_FROM_IP and DDS_RTPS_AUTO_ID_FROM_MAC for additional information.
(Legacy) When rtps_auto_id_kind is set to DDS_RTPS_AUTO_ID_FROM_MAC, the 96-bit prefix is generated as follows:

rtps_host_id: the first 32 bits of the MAC address of the first up and running interface of the host machine are assigned.
rtps_app_id: the last 32 bits of the MAC address of the first up and running interface of the host machine are assigned.
rtps_instance_id: this field is split into two different parts. The process (or task) ID is assigned to the first 24 bits. A counter is assigned to the last 8 bits. This counter is incremented per new participant. In both scenarios, you can change the value of each field independently.

DDS_RTPS_AUTO_ID_FROM_IP is not a good algorithm to guarantee prefix uniqueness because the process ID can be recycled by the OSs. See 44.9.3.2 Uniqueness Problem with DDS_RTPS_AUTO_ID_FROM_IP and DDS_RTPS_AUTO_ID_FROM_MAC for additional information.

44.9.3.1 Overwriting the Default RTPS 96-bit Prefix

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.

Get the DomainParticipant QoS from the DomainParticipantFactory:

DDS_DomainParticipantFactory_get_default_participant_qos(
		DDS_DomainParticipantFactory_get_instance(),
		&participant_qos);

Change the WireProtocolQosPolicy using one of the following options.

Use DDS_RTPS_AUTO_ID_FROM_MAC to explicitly set just the application/task identifier portion of the rtps_instance_id field:

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

Only set the per participant counter and let Connext handle the application/task identifier:

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

Set the entire rtps_instance_id field yourself:

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 will take responsibility for them).

RTI recommends that you always specify the two parts separately in order to avoid errors.

Let Connext handle the entire rtps_instance_id field:

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 will take responsibility for them). RTI recommends that you always specify the two parts separately in order to clearly show the difference.

Create the DomainParticipant as usual using the modified QoS structure instead of the default one.

44.9.3.2 Uniqueness Problem with DDS_RTPS_AUTO_ID_FROM_IP and DDS_RTPS_AUTO_ID_FROM_MAC

This section applies only when rtps_auto_id_kind is set to DDS_RTPS_AUTO_ID_FROM_IP or DDS_RTPS_AUTO_ID_FROM_MAC.

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’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, 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 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 44.3 DISCOVERY_CONFIG QosPolicy (DDS Extension), 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.

44.9.4 Properties

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

44.9.5 Related QosPolicies

44.3 DISCOVERY_CONFIG QosPolicy (DDS Extension)

44.9.6 Applicable DDS Entities

16.3 DomainParticipants

44.9.7 System Resource Considerations

The use of this policy does not significantly impact the use of resources.