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

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

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 . For defaults and valid ranges, please refer to the API Reference HTML documentation.

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

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.

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

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

  3. In this scenario, Connext DDS rtps_auto_id_kind: is set to 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.
  4. 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.

  5. In this scenario, rtps_auto_id_kind is set to RTPS_AUTO_ID_FROM_UUID. As the name suggests, this alternative mechanism uses a unique, randomly generated UUID to fill the rtps_host_id, rtps_app_id, or rtps_instance_id fields.
  6. 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.

  1. Get the DomainParticipant QoS from the DomainParticipantFactory:
DDS_DomainParticipantFactory_get_default_participant_qos(
		DDS_DomainParticipantFactory_get_instance(),
		&participant_qos); 
  1. Change the WireProtocolQosPolicy using one of the following options.
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.

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

Applicable DDS Entities

System Resource Considerations

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

© 2016 RTI