.. _configuring_aliasing:

Configuring ROS 2 Topic and Type Aliasing in Connext
====================================================

*Connext*-only applications using 7.5.0 or later can enable topic aliasing with
the following properties.

dds.ros.enable_interoperability
-------------------------------
Default: False

The `dds.ros.enable_interoperability <https://community.rti.com/static/documentation/connext-dds/current/doc/manuals/connext_dds_professional/properties_reference/property_full.html#dds-ros>`__
property enables ROS 2 topic and type mangling in *Connext*
as described in :ref:`understanding_aliasing`. When this property is
set to true on the participant QoS, all entities created by that participant
will have topic and type mangling enabled. When set on the writer or reader
QoS, only writers or readers loading that QoS profile for which the
property is enabled will have topic and type mangling enabled. The value
set in the writer or reader QoS overrides the value
set in the participant QoS, if it is set in both places. 

Here is an example XML snippet that sets the property to true:

.. code-block:: xml

    <property>
        <value>
            <element>
                <name>dds.ros.enable_interoperability</name>
                <value>true</value>
            </element>
        </value>
    </property>


dds.ros.use_mangled_names_as_default
------------------------------------
Default: 

- True when ``dds.ros.enable_interoperability`` is true 
- False when ``dds.ros.enable_interoperability`` is false

The `dds.ros.use_mangled_names_as_default <https://community.rti.com/static/documentation/connext-dds/current/doc/manuals/connext_dds_professional/properties_reference/property_full.html#dds-ros>`__
property configures whether the *Connext* topic name is announced as
the primary topic name or as a topic alias, as well as whether the
*Connext* type name is announced as the primary type name or as a type
alias. See :ref:`understanding_aliasing`.

See :ref:`enable-connext750-any-rmw` for brief tutorials on enabling ROS 2
topic aliasing in your *Connext* applications. (The tutorials quickly guide
you through both setting the property *and* getting the endpoints to
communicate.)

.. attention::

    For the purposes of this scenario (:ref:`enable-connext750-any-rmw`),
    leave this property set to true.

When this property is set to true, |CONNEXT| applications will announce the
mangled ROS 2 topic name as the primary topic name and announce the
|CONNEXT| topic name as a topic alias. This allows |CONNEXT| 7.5.0-and-later
applications to communicate with ROS 2 applications with any RMW, which is the
scenario we are documenting in :ref:`enable-connext750-any-rmw`.

Note that setting this property to true—although enabling communication between
ROS 2 and |CONNEXT| 7.5.0-and-later applications—precisely prevents communication with |CONNEXT|
applications *before* 7.5.0. This is because
applications before 7.5.0 use the |CONNEXT| topic name and don't recognize topic aliases.
So, when this property is set to true, a |CONNEXT| 7.5.0-and-later application with
topic "Foo" can communicate with a ROS 2 application with topic "Foo", but
cannot communicate with a |CONNEXT| 7.3.0 application with topic "Foo."

Conversely, when ``dds.ros.use_mangled_names_as_default`` is set to false,
|CONNEXT| applications will announce the |CONNEXT| topic name as its primary
topic and announce the mangled ROS 2 topic name as its topic alias. This allows
|CONNEXT| applications to communicate with |CONNEXT| applications *before*
7.5.0, but prevents communication with ROS 2 applications—*unless* those ROS 2
applications are using a |CONNEXT| RMW with a 7.5.0-or-later version of
|CONNEXT|. A 7.5.0-or-later |CONNEXT| RMW can handle both the
primary topic and topic alias, thus enabling communication even when
``dds.ros.use_mangled_names_as_default`` is set to false.
(Using the |CONNEXT| RMW with a 7.5.0-or-later version of |CONNEXT|
is currently experimental.)