Built-in Topics#

Introduction#

In OpenDDS, built-in topics are created and published by default to exchange information about DDS participants operating in the deployment. When OpenDDS is InfoRepo Discovery, the built-in topics are published by this service. For RTPS Discovery, the internal OpenDDS implementation instantiated in a process populates the caches of the built-In topic DataReaders.

The IDL struct BuiltinTopicKey_t is used by the built-in topics. This structure contains an array of 16 octets (bytes) which corresponds to an InfoRepo identifier or a DDSI-RTPS GUID.

Built-in Topics for DCPSInfoRepo Configuration#

When starting the DCPSInfoRepo a command line option of -NOBITS may be used to suppress publication of built-in topics.

Four separate topics are defined for each domain. Each is dedicated to a particular entity (domain participant DCPSParticipant Topic, topic DCPSParticipant Topic, data writer DCPSPublication Topic, data reader DCPSSubscription Topic) and publishes instances describing the state for each entity in the domain.

Subscriptions to built-in topics are automatically created for each domain participant. A participant’s support for built-in topics can be toggled via the [common] DCPSBit configuration option. To view the built-in topic data, simply obtain the built-in Subscriber and then use it to access the Data Reader for the built-in topic of interest. The Data Reader can then be used like any other Data Reader.

See Built-in Topic Subscription Example for an example showing how to read from a built-in topic.

If you are not planning on using built-in topics in your application, you can configure OpenDDS to remove built-in topic support at build time. Doing so can reduce the footprint of the core DDS library by up to 30%. See Disabling the Building of Built-in Topic Support for information on disabling built-in topic support.

DCPSParticipant Topic#

The DCPSParticipant topic publishes information about the Domain Participants of the Domain. Here is the IDL that defines the structure published for this topic:

struct ParticipantBuiltinTopicData {
  BuiltinTopicKey_t key;
  UserDataQosPolicy user_data;
};

Each Domain Participant is defined by a unique key and is its own instance within this topic.

DCPSTopic Topic#

Note

OpenDDS does not support this built-in topic when configured for RTPS Discovery.

The DCPSTopic topic publishes information about the topics in the domain. Here is the IDL that defines the structure published for this topic:

struct TopicBuiltinTopicData {
  BuiltinTopicKey_t key;
  string name;
  string type_name;
  DurabilityQosPolicy durability;
  QosPolicy deadline;
  LatencyBudgetQosPolicy latency_budget;
  LivelinessQosPolicy liveliness;
  ReliabilityQosPolicy reliability;
  TransportPriorityQosPolicy transport_priority;
  LifespanQosPolicy lifespan;
  DestinationOrderQosPolicy destination_order;
  HistoryQosPolicy history;
  ResourceLimitsQosPolicy resource_limits;
  OwnershipQosPolicy ownership;
  TopicDataQosPolicy topic_data;
};

Each topic is identified by a unique key and is its own instance within this built-in topic. The members above identify the name of the topic, the name of the topic type, and the set of QoS policies for that topic.

DCPSPublication Topic#

The DCPSPublication topic publishes information about the Data Writers in the Domain. Here is the IDL that defines the structure published for this topic:

struct PublicationBuiltinTopicData {
  BuiltinTopicKey_t key;
  BuiltinTopicKey_t participant_key;
  string topic_name;
  string type_name;
  DurabilityQosPolicy durability;
  DeadlineQosPolicy deadline;
  LatencyBudgetQosPolicy latency_budget;
  LivelinessQosPolicy liveliness;
  ReliabilityQosPolicy reliability;
  LifespanQosPolicy lifespan;
  UserDataQosPolicy user_data;
  OwnershipStrengthQosPolicy ownership_strength;
  PresentationQosPolicy presentation;
  PartitionQosPolicy partition;
  TopicDataQosPolicy topic_data;
  GroupDataQosPolicy group_data;
};

Each Data Writer is assigned a unique key when it is created and defines its own instance within this topic. The fields above identify the Domain Participant (via its key) that the Data Writer belongs to, the topic name and type, and the various QoS policies applied to the Data Writer.

DCPSSubscription Topic#

The DCPSSubscription topic publishes information about the Data Readers in the Domain. Here is the IDL that defines the structure published for this topic:

struct SubscriptionBuiltinTopicData {
  BuiltinTopicKey_t key;
  BuiltinTopicKey_t participant_key;
  string topic_name;
  string type_name;
  DurabilityQosPolicy durability;
  DeadlineQosPolicy deadline;
  LatencyBudgetQosPolicy latency_budget;
  LivelinessQosPolicy liveliness;
  ReliabilityQosPolicy reliability;
  DestinationOrderQosPolicy destination_order;
  UserDataQosPolicy user_data;
  TimeBasedFilterQosPolicy time_based_filter;
  PresentationQosPolicy presentation;
  PartitionQosPolicy partition;
  TopicDataQosPolicy topic_data;
  GroupDataQosPolicy group_data;
};

Each Data Reader is assigned a unique key when it is created and defines its own instance within this topic. The fields above identify the Domain Participant (via its key) that the Data Reader belongs to, the topic name and type, and the various QoS policies applied to the Data Reader.

Built-in Topic Subscription Example#

The following code uses a domain participant to get the built-in subscriber. It then uses the subscriber to get the Data Reader for the DCPSParticipant topic and subsequently reads samples for that reader.

Subscriber_var bit_subscriber = participant->get_builtin_subscriber();
DDS::DataReader_var dr =
  bit_subscriber->lookup_datareader(BUILT_IN_PARTICIPANT_TOPIC);
DDS::ParticipantBuiltinTopicDataDataReader_var part_dr =
  DDS::ParticipantBuiltinTopicDataDataReader::_narrow(dr);

DDS::ParticipantBuiltinTopicDataSeq part_data;
DDS::SampleInfoSeq infos;
DDS::ReturnCode_t ret = part_dr->read(part_data, infos, 20,
                                      DDS::ANY_SAMPLE_STATE,
                                      DDS::ANY_VIEW_STATE,
                                      DDS::ANY_INSTANCE_STATE);

// Check return status and read the participant data

The code for the other built-in topics is similar.

OpenDDS-specific Built-in Topics#

OpenDDSParticipantLocation Topic#

The built-in topic OpenDDSParticipantLocation is published by the DDSI-RTPS discovery implementation to give applications visibility into the details of how each remote participant is connected over the network. If the RtpsRelay (The RtpsRelay) and/or IETF ICE (Interactive Connectivity Establishment (ICE) for RTPS) are enabled, their usage is reflected in the OpenDDSParticipantLocation topic data. The topic type ParticipantLocationBuiltinTopicData is defined in dds/OpenddsDcpsExt.idl in the OpenDDS::DCPS module:

  • guid (key) – The GUID of the remote participant. Also, a key into the DCPSParticipant topic.

  • location – A bit-mask indicating which fields are populated.

  • change_mask – A bit-mask indicating which fields changed.

  • local_addr – SPDP address of the remote participant for a local connection.

  • local_timestamp – Time that local_addr was set.

  • ice_addr – SPDP address of the remote participant for an ICE connection.

  • ice_timestamp – Time that ice_addr was set.

  • relay_addr – SPDP address of the remote participant using the RtpsRelay.

  • relay_timestamp – Time that relay_addr was set.

  • local6_addr, local6_timestamp, ice6_addr, ice6_timestamp, relay6_addr, and relay6_timestamp – Are the IPV6 equivalents.

  • lease_duration – The remote participant’s [rtps_discovery] LeaseDuration

OpenDDSConnectionRecord Topic#

The built-in topic OpenDDSConnectionRecord is published by the DDSI-RTPS discovery implementation and RTPS_UDP transport implementation to give applications visibility into the details of a participant’s connection to an RtpsRelay instance. Security must be enabled in the build of OpenDDS (Building OpenDDS with Security Enabled) to use this topic.

The topic type ConnectionRecord is defined in dds/OpenddsDcpsExt.idl in the OpenDDS::DCPS module:

  • guid (key) – The GUID of the remote participant. Also, a key into the DCPSParticipant topic.

  • address (key) – The address of the remote participant.

  • protocol (key) – The method used to determine connectivity. Currently, “RtpsRelay:STUN” is the only supported protocol.

  • latency – A measured round-trip latency for protocols that support it.

OpenDDSInternalThread Topic#

The built-in topic OpenDDSInternalThread is published when OpenDDS is configured with [common] DCPSThreadStatusInterval. When enabled, the DataReader for this built-in topic will report the status of threads created and managed by OpenDDS within the current process. The timestamp associated with samples can be used to determine the health (responsiveness) of the thread.

The topic type InternalThreadBuiltinTopicData is defined in dds/OpenddsDcpsExt.idl in the OpenDDS::DCPS module:

  • thread_id (key) – A string identifier for the thread.

  • utilization – Estimated utilization of this thread (0.0-1.0).