.. include:: vars.rst

.. _section-introduction:

Introduction
************

|RTI_w_TM| |CDS| is a stand-alone application that deploys |RTI| |CONNEXT_w_TM|
applications in dynamic environments where UDP/IP multicast is not available.
This is typical of wide-area networks or some cloud-based environments where
the routers and switches may disable IP multicast forwarding.

DDS has a builtin Discovery Service that allows all DDS applications to
automatically detect the presence of other applications and discover the Topics
they publish and subscribe along with the associated data types and |Qos| (QoS).

The builtin discovery service primarily relies on UDP/IP multicast to
bootstrap the detection of other DDS applications and learn their network
addresses. The use of UDP/IP multicast allows DDS discovery to be completely
peer-to-peer. That is, it can operate without requiring any additional services
or brokers. The applications themselves can discover each other directly.

However, if |CONNEXT| applications run in environments where UDP/IP
multicast is not available, then builtin (peer-to-peer) discovery is not
sufficient. |CONNEXT| offers two mechanisms to help with those scenarios:

* For static environments where the network addresses of all the applications
  are known a-priori, you can configure your application to automatically check
  on these addresses for the presence of other applications. This is
  accomplished by configuring the :link_connext_dds_pro_um:`Initial Peers
  <#users_manual/ConfigPeersListUsed_inDiscov.htm#discovery_507287096_336417>`.

* For dynamic environments where the network addresses are not known
  in advance, or in cases where the list is too large or cumbersome to
  manage, you can leverage |RTI_CDS|. This external service acts as a reliable
  "rendezvous" point for |CONNEXT| applications to learn about the presence and
  network addresses of other DDS applications. You can do this by
  setting the :link_connext_dds_pro_um:`Initial Peers
  <#users_manual/ConfigPeersListUsed_inDiscov.htm#discovery_507287096_336417>`
  to include |CDS|.

* For WAN deployments where applications require Network Address Translator (NAT) 
  traversal. |CDS| can aid in this process in combination with |RTI_RWT|. See 
  :link_connext_dds_pro_um:`RTI Real-Time WAN Transport <#users_manual/PartRealtimeWAN.htm>`.

.. figure:: static/CdsOverview.svg
    :figwidth: 100 %
    :alt: Cloud Discovery Service Overview
    :name: FigureCdsOverview
    :align: center

    Cloud Discovery Service Overview

:numref:`FigureCdsOverview` shows a simple representation of the
operation of |CDS|. It acts as a  "relay" service that forwards the
bootstrap (participant announcement) messages that allow |DPs| to
learn about the presence of other |DPs|.


.. _section-Introduction-Basics:

The Basics
==========

|CDS| operates using the standard |SDP| (SPDP) [#DDS_SDP]_. In SPDP, |DPs|
initially announce their presence to all the specified
:link_connext_dds_pro_um:`Initial Peers
<#users_manual/ConfigPeersListUsed_inDiscov.htm#discovery_507287096_336417>`.
These *participant announcements* contain the necessary information for other
|DPs| to discover their presence and bootstrap communications. These messages
are also used to maintain participant liveliness. 

.. figure:: static/CdsParticipantAnnouncementRelay.svg
    :figwidth: 100 %
    :alt: Cloud Discovery Service forwards Participant Announcement messages
    :name: CdsParticipantAnnouncementRelay
    :align: center

    Cloud Discovery Service forwards Participant Announcement messages


|CDS| listens for participant announcements to dynamically learn about the
current list of |DPs|, their DDS domain IDs, and their network
addresses.

:numref:`CdsParticipantAnnouncementRelay` illustrates that each |DP|
includes a |CDS| instance in its :link_connext_dds_pro_um:`Initial Peers
<#users_manual/ConfigPeersListUsed_inDiscov.htm#discovery_507287096_336417>`.
Hence, the |DP| will send *participant announcements* to |CDS|, which will
forward those announcements to the list of |DPs| it knows about, enabling them
to initiate the discovery process among themselves.

.. figure:: static/CdsParticipantAnouncement.svg
    :figwidth: 100 %
    :alt: Domain Participants exchange Participant Announcement messages
    :name: CdsParticipantAnouncement
    :align: center

    |DPs| exchange Participant Announcement messages

:numref:`CdsParticipantAnouncement` illustrates that once a |DP|
discovers the presence of another one (via the forwarded message from |CDS|) it
sends its Participant Announcement messages directly. This step is the same as
if the |DP| had included the other |DP| in its
:link_connext_dds_pro_um:`Initial Peers
<#users_manual/ConfigPeersListUsed_inDiscov.htm#discovery_507287096_336417>` or
was using multicast to announce its presence. These messages are also used to
maintain participant liveliness.

.. figure:: static/CdsEndpointDiscovery.svg
    :figwidth: 100 %
    :alt: Domain Participants exchange Endpoint Discovery messages
    :name: CdsEndpointDiscovery
    :align: center

    |DPs| exchange Endpoint Discovery messages

:numref:`CdsEndpointDiscovery` illustrates that once |DPs| know about each
other, they exchange Endpoint discovery information. That is, they
exchange information about the DataWriters and DataReaders each one has.
This step is unaltered by the presence of |CDS|.

Direct benefits of |CDS|:

* Dynamic discovery remains possible even if multicast
  is not available, without the need to anticipate or maintain a list of peers.
* |CDS| integrates seamlessly in a DDS environment.
  Because it operates at the RTPS [#RTPS]_ level, |CONNEXT| applications do
  not need any special behavior or protocol. They just need to configure their
  :link_connext_dds_pro_um:`Initial Peers
  <#users_manual/ConfigPeersListUsed_inDiscov.htm#discovery_507287096_336417>`
  to contain the location where |CDS| is running. Since this is all
  configurable at runtime, there is no need to recompile your application.
  This implies that |CDS| will also work with existing services such as *RTI
  Routing Service*, |RTI_CONNEXT| *Micro*, or other implementations of
  DDS-RTPS.
* Discovery remains a distributed process performed among all the |DPs|.
  This allows you to scale the system dynamically. It also avoids having
  centralized and bottleneck servers.

For a deeper understanding of discovery, refer to
:link_connext_dds_pro_um:`Discovery Overview <#users_manual/Discovery.htm>` 
in the |CORE_MANUAL|.

Available Documentation
=======================

In this manual you can find:

- :ref:`Introduction <section-introduction>`
- :ref:`Installation <section-installation>`
- :ref:`Core Concepts <section-core-concepts>`
- :ref:`Configuration <section-configuration>`
- :ref:`Usage <section-usage>`
- :ref:`Tutorials <section-tutorials>`
- :ref:`Troubleshooting <section-troubleshooting>`
- :ref:`Release Notes <section-release-notes>`

.. _section-Paths-In-Documentation:

Paths Mentioned in Documentation
================================

This documentation refers to:

- ``<NDDSHOME>`` This refers to the installation directory for |CONNEXT|.
  The default installation paths are:

  - macOS® systems:
    ``/Applications/rti_connext_dds-version``
  - Linux® systems, non-root user:
    ``/home/your user name/rti_connext_dds-version``
  - Linux systems, root user:
    ``/opt/rti_connext_dds-version``
  - Windows® systems, user without Administrator privileges:
    ``<your home directory>\rti_connext_dds-version``
  - Windows systems, user with Administrator privileges:
    ``C:\Program Files\rti_connext_dds-version``

  You may also see ``$NDDSHOME`` or ``%NDDSHOME%``, which refers to an
  environment variable set to the installation path.

  Whenever you see ``<NDDSHOME>`` used in a path, replace it with your
  installation path.

  **Note for Windows Users:** When using a command prompt to enter a command
  that includes the path ``C:\Program Files`` (or any directory name that
  has a space), enclose the path in quotation marks. For example:
  ``“C:\Program Files\rti_connext_dds-version\bin\rticlouddiscoveryservice.bat”``

  Or if you have defined the ``NDDSHOME`` environment variable:
  ``"%NDDSHOME%\bin\rticlouddiscoveryservice.bat"``
- ``<path to examples>`` By default, examples are copied into your home
  directory the first time you run *RTI Launcher* or any script in
  ``<NDDSHOME>/bin``. This document refers to the location of the copied
  examples as ``<path to examples>``.

  Wherever you see ``<path to examples>``, replace it with the appropriate path.
  Default path to the examples:

  - macOS systems:
    ``/Users/your user name/rti_workspace/version/examples``
  - Linux systems:
    ``/home/your user name/rti_workspace/version/examples``
  - Windows systems:
    ``your Windows documents folder\rti_workspace\version\examples``.
    Where ``'your Windows documents folder'`` depends on your version of
    Windows. For example, on Windows 7, the folder is
    ``C:\Users\your user name\Documents``; on Windows Server 2003, the folder
    is ``C:\Documents and Settings\your user name\Documents``.

- ``<RTIMEHOME>`` This environment variable must be set to the installation 
  directory path for |CONNEXT_MICRO|. If you installed |CONNEXT_PRO| 
  with default settings, this will be in: 
  ``<path_to_connext_dds_installation>/rti_connext_dds-version/rti_connext_micro-version``. 
  If you have copied |CONNEXT_MICRO| to another place, set ``RTIMEHOME`` to point to that location. 

.. rubric:: References

.. [#DDS_SDP] DDS Simple Discovery Protocol
.. [#RTPS] Real-Time Publish-Subscribe Protocol