WIRE_PROTOCOL QosPolicy (DDS Extension)

You are here: Part 2: Core Concepts > Working with DDS Domains > DomainParticipant QosPolicies > WIRE_PROTOCOL QosPolicy (DDS Extension)

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

It includes the members in Table 19 . 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 19 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 Choosing Participant IDs.
DDS_UnsignedLong	rtps_host_id	A machine/OS-specific host ID, unique in the DDS domain. See Host, App, and Instance IDs.
	rtps_app_id	A participant-specific ID, unique within the scope of the rtps_host_id. See Host, App, and Instance IDs.
	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 Host, App, and Instance IDs.
DDS_RtpsWellKnownPorts_t	rtps_well_known _ports	Determines the well-known multicast and unicast ports for discovery and user traffic. See 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.

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.

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

Automatic Participant ID Selection

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:

Change the verbosity level of the NDDS_CONFIG_LOG_CATEGORY_API category to NDDS_CONFIG_LOG_VERBOSITY_STATUS_LOCAL (see Controlling Messages from Connext DDS).
Call get_qos() and look at the participant_id value in the 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 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.

Host, App, and Instance IDs

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

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

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

Table 20 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 Ports Used for Discovery.
	participant_id_gain	Tunable gain parameters. See Ports Used for Discovery.
	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

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

rtps_host_id
rtps_app_id
rtps_instance_id

Depending on the rtps_auto_id_kind value, there are two different scenarios:

In the default and most common scenario, rtps_auto_id_kind is set to DDS_RTPS_AUTO_ID_FROM_IP. Doing so, each field is interpreted 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
- rtps_app_id: the process (or task) ID is assigned
- rtps_instance_id: A counter is assigned that is incremented per new participant

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.

In this scenario, Connext DDS provides a different value for rtps_auto_id_kind: DDS_RTPS_AUTO_ID_FROM_MAC. As the name suggests, this alternative mechanism uses the MAC address instead of the IPv4 address. Since the MAC address size is up to 64 bits, the logical mapping of the host information, the application ID, and the instance identifiers has to change.

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:

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.

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.

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

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

Let Connext DDS 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 DDS 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.

Example

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.

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

Related QosPolicies

DISCOVERY_CONFIG QosPolicy (DDS Extension)

Applicable DDS Entities

DomainParticipants

System Resource Considerations

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