From 3358ca5736266042043f701dd4a647cd887fcf38 Mon Sep 17 00:00:00 2001 From: Zakaria Talbi Lalmi Date: Tue, 26 May 2026 11:52:03 +0200 Subject: [PATCH 1/3] Documented changes for Topic Profile Lookup Signed-off-by: Zakaria Talbi Lalmi --- docs/rst/notes/forthcoming_version.rst | 14 +++++++ docs/rst/user_manual/configuration.rst | 9 ++++ docs/rst/user_manual/participants/xml.rst | 50 +++++++++++++++++++++++ 3 files changed, 73 insertions(+) diff --git a/docs/rst/notes/forthcoming_version.rst b/docs/rst/notes/forthcoming_version.rst index eac3087ed..89350a22e 100644 --- a/docs/rst/notes/forthcoming_version.rst +++ b/docs/rst/notes/forthcoming_version.rst @@ -6,3 +6,17 @@ Forthcoming Version ################### +This release includes the following **new features**: + +* :ref:`XML Participant ` now supports topic-name endpoint profile lookup: + when creating a :term:`DataWriter` or :term:`DataReader` for a topic, a loaded XML profile whose name + matches the topic name is automatically applied, giving users full control over QoS fields such as + history, memory policy and transport. + A new optional ``xml-override`` tag allows the user to force YAML QoS to take precedence over a matching XML profile. + For more details, see :ref:`user_manual_participants_xml_topic_profiles`. + +This release includes the following **documentation updates**: + +* Document topic-name endpoint profile lookup for the :ref:`XML Participant `, + including QoS fields always enforced by the *DDS Router* regardless of the profile. +* Add *Endpoint Profiles* section to the :ref:`user_manual_configuration` page. \ No newline at end of file diff --git a/docs/rst/user_manual/configuration.rst b/docs/rst/user_manual/configuration.rst index 0f8f71853..1c54cf4de 100644 --- a/docs/rst/user_manual/configuration.rst +++ b/docs/rst/user_manual/configuration.rst @@ -90,6 +90,15 @@ Under the **optional** tag ``raw``, an XML configuration (with the same format a These QoS should be configured by the user explicitly. Check :ref:`user_manual_participants_xml_profiles`. +Endpoint profiles +----------------- + +Profiles named after a topic are automatically applied to :term:`DataWriter` and :term:`DataReader` endpoints +when they are created for that topic by an :ref:`XML Participant `. +By default, when a matching profile is found, the YAML QoS configuration is ignored for that endpoint (XML takes priority). +This behaviour can be changed via the xml-override tag on the participant. +For more details, see :ref:`user_manual_participants_xml_topic_profiles`. + Topics Configuration ==================== diff --git a/docs/rst/user_manual/participants/xml.rst b/docs/rst/user_manual/participants/xml.rst index 3db951401..ff9ea89ee 100644 --- a/docs/rst/user_manual/participants/xml.rst +++ b/docs/rst/user_manual/participants/xml.rst @@ -74,6 +74,56 @@ Notice that not setting such QoS will not affect the correct functionality of th +.. _user_manual_participants_xml_topic_profiles: + +Topic-name endpoint profile lookup +----------------------------------- +When the XML Participant creates a DataWriter or DataReader for a topic, it looks for a loaded XML profile +whose name matches the topic name. +If a matching profile is found, the endpoint is configured using that profile's QoS, giving the user full +control over fields such as history, memory policy, transport, etc. +If no matching profile exists, the endpoint falls back to default QoS with values derived from the YAML configuration. + +By default, when a matching XML profile is found, the YAML QoS configuration is ignored for that endpoint. +This behaviour can be changed by setting the xml-override tag to true in the participant configuration. +When enabled, the YAML QoS values (durability, reliability, ownership, history) will override those from the XML profile. + +.. note:: + + Certain QoS are always enforced by the |ddsrouter| regardless of the XML profile or the ``xml-override`` setting: + deadline on DataWriters (set to minimum so it matches any reader), + ``autodispose_unregistered_instances`` on DataWriters (set to ``false`` to preserve dispose/unregister forwarding semantics), + and ``expects_inline_qos`` on DataReaders for keyed topics. + +The following example loads a profile named ``my_topic`` that will be automatically applied when creating +endpoints for a topic of that name: + + +**YAML** + +.. code-block:: yaml + + - name: xml_participant + kind: xml + xml-override: true + + +**XML** + +.. code-block:: xml + + + + + DYNAMIC + + + DYNAMIC + + + + + Repeater -------- From 3f5dcb726255f85ebaa7207e1321ee3211654ee5 Mon Sep 17 00:00:00 2001 From: Zakaria Talbi Lalmi Date: Thu, 9 Jul 2026 12:41:53 +0200 Subject: [PATCH 2/3] Updated docs changes to include the latest functionality changes Signed-off-by: Zakaria Talbi Lalmi --- docs/rst/notes/forthcoming_version.rst | 6 ++- docs/rst/spelling_wordlist.txt | 1 + docs/rst/user_manual/configuration.rst | 7 ++- docs/rst/user_manual/participants/xml.rst | 56 +++++++++++++++-------- 4 files changed, 46 insertions(+), 24 deletions(-) diff --git a/docs/rst/notes/forthcoming_version.rst b/docs/rst/notes/forthcoming_version.rst index 89350a22e..8ecc0ed13 100644 --- a/docs/rst/notes/forthcoming_version.rst +++ b/docs/rst/notes/forthcoming_version.rst @@ -12,11 +12,13 @@ This release includes the following **new features**: when creating a :term:`DataWriter` or :term:`DataReader` for a topic, a loaded XML profile whose name matches the topic name is automatically applied, giving users full control over QoS fields such as history, memory policy and transport. - A new optional ``xml-override`` tag allows the user to force YAML QoS to take precedence over a matching XML profile. + A specific profile can also be selected per topic via the new ``endpoint-profile-name`` tag. + A new optional ``endpoint-qos-mode`` participant tag controls whether YAML QoS overrides the matching + XML profile (``xml-overridable``, default) or the profile is applied verbatim (``xml-standalone``). For more details, see :ref:`user_manual_participants_xml_topic_profiles`. This release includes the following **documentation updates**: * Document topic-name endpoint profile lookup for the :ref:`XML Participant `, including QoS fields always enforced by the *DDS Router* regardless of the profile. -* Add *Endpoint Profiles* section to the :ref:`user_manual_configuration` page. \ No newline at end of file +* Add *Endpoint Profiles* section to the :ref:`user_manual_configuration` page. diff --git a/docs/rst/spelling_wordlist.txt b/docs/rst/spelling_wordlist.txt index b811c937f..4f047921c 100644 --- a/docs/rst/spelling_wordlist.txt +++ b/docs/rst/spelling_wordlist.txt @@ -43,6 +43,7 @@ Requiredness runtime scalable Tsan +unregister utils validator Vulcanexus diff --git a/docs/rst/user_manual/configuration.rst b/docs/rst/user_manual/configuration.rst index 1c54cf4de..b906e39bb 100644 --- a/docs/rst/user_manual/configuration.rst +++ b/docs/rst/user_manual/configuration.rst @@ -95,8 +95,11 @@ Endpoint profiles Profiles named after a topic are automatically applied to :term:`DataWriter` and :term:`DataReader` endpoints when they are created for that topic by an :ref:`XML Participant `. -By default, when a matching profile is found, the YAML QoS configuration is ignored for that endpoint (XML takes priority). -This behaviour can be changed via the xml-override tag on the participant. +A specific profile can also be selected per topic via the ``endpoint-profile-name`` tag, instead of relying +on the topic name. +By default, QoS fields explicitly set in the YAML configuration override the matching XML profile's values +(``endpoint-qos-mode: xml-overridable``); this can be changed to ``xml-standalone`` on the participant so the +XML profile is applied verbatim. For more details, see :ref:`user_manual_participants_xml_topic_profiles`. Topics Configuration diff --git a/docs/rst/user_manual/participants/xml.rst b/docs/rst/user_manual/participants/xml.rst index ff9ea89ee..3b64eb47d 100644 --- a/docs/rst/user_manual/participants/xml.rst +++ b/docs/rst/user_manual/participants/xml.rst @@ -78,19 +78,16 @@ Notice that not setting such QoS will not affect the correct functionality of th Topic-name endpoint profile lookup ----------------------------------- -When the XML Participant creates a DataWriter or DataReader for a topic, it looks for a loaded XML profile -whose name matches the topic name. -If a matching profile is found, the endpoint is configured using that profile's QoS, giving the user full +When the XML Participant creates a DataWriter or DataReader for a topic, it looks for a loaded XML ``data_writer`` +or ``data_reader`` profile to configure that endpoint. +By default, the |ddsrouter| looks for a profile **whose name matches the topic name**. +If a matching profile is found, the endpoint is configured using that profile's QoS, giving the user control over fields such as history, memory policy, transport, etc. If no matching profile exists, the endpoint falls back to default QoS with values derived from the YAML configuration. -By default, when a matching XML profile is found, the YAML QoS configuration is ignored for that endpoint. -This behaviour can be changed by setting the xml-override tag to true in the participant configuration. -When enabled, the YAML QoS values (durability, reliability, ownership, history) will override those from the XML profile. - .. note:: - Certain QoS are always enforced by the |ddsrouter| regardless of the XML profile or the ``xml-override`` setting: + Certain QoS are always enforced by the |ddsrouter| regardless of the XML profile: deadline on DataWriters (set to minimum so it matches any reader), ``autodispose_unregistered_instances`` on DataWriters (set to ``false`` to preserve dispose/unregister forwarding semantics), and ``expects_inline_qos`` on DataReaders for keyed topics. @@ -98,18 +95,6 @@ When enabled, the YAML QoS values (durability, reliability, ownership, history) The following example loads a profile named ``my_topic`` that will be automatically applied when creating endpoints for a topic of that name: - -**YAML** - -.. code-block:: yaml - - - name: xml_participant - kind: xml - xml-override: true - - -**XML** - .. code-block:: xml @@ -123,6 +108,37 @@ endpoints for a topic of that name: +Selecting a profile explicitly +""""""""""""""""""""""""""""""" + +Instead of relying on the topic name, a specific profile can be selected for a topic with the +``endpoint-profile-name`` tag under that topic's QoS configuration. +When set, the |ddsrouter| looks up the XML profile with that name instead of the topic name: + +.. code-block:: yaml + + topics: + - name: "rt/chatter" + qos: + endpoint-profile-name: "my_reader_profile" + +Overriding profile QoS from the YAML configuration +""""""""""""""""""""""""""""""""""""""""""""""""""" + +When a matching XML profile is applied, the QoS fields explicitly set by the user in the YAML +configuration take precedence over the values in the XML profile. +This behavior is controlled by the ``endpoint-qos-mode`` participant tag, which accepts two values: + +* ``xml-overridable`` *(default)*: the XML profile is applied first, and any QoS field explicitly set in + the YAML configuration overrides the corresponding value from the profile. +* ``xml-standalone``: the XML profile is applied verbatim; YAML QoS does not override it. + +.. code-block:: yaml + + - name: xml_participant + kind: xml + endpoint-qos-mode: xml-standalone + Repeater -------- From 7958efa53fd0e693db806983f10b1160009a0128 Mon Sep 17 00:00:00 2001 From: Zakaria Talbi Lalmi Date: Fri, 2 Oct 2026 08:58:26 +0200 Subject: [PATCH 3/3] Docs update after topic profile lookup refactor Signed-off-by: Zakaria Talbi Lalmi --- .../docu_example.yaml | 13 ++++ docs/rst/notes/forthcoming_version.rst | 18 ++--- docs/rst/user_manual/configuration.rst | 32 ++++++-- docs/rst/user_manual/participants/xml.rst | 77 ++++++++++--------- .../ddsrouter_config_schema.json | 3 + 5 files changed, 90 insertions(+), 53 deletions(-) diff --git a/ddsrouter_yaml/test/unittest/ddsrouter_yaml_validator/valid_config_files_router/docu_example.yaml b/ddsrouter_yaml/test/unittest/ddsrouter_yaml_validator/valid_config_files_router/docu_example.yaml index 7429d1430..8cd545581 100644 --- a/ddsrouter_yaml/test/unittest/ddsrouter_yaml_validator/valid_config_files_router/docu_example.yaml +++ b/ddsrouter_yaml/test/unittest/ddsrouter_yaml_validator/valid_config_files_router/docu_example.yaml @@ -44,6 +44,12 @@ xml: 1 + + DYNAMIC + + + DYNAMIC + # Relay topic rt/chatter and type std_msgs::msg::dds_::String_ @@ -70,6 +76,13 @@ topics: - Participant0 - Participant1 + - name: HelloWorldTopic + type: HelloWorld + qos: + endpoint-profile-name: "custom_endpoint_profile" + participants: + - xml_participant + # Do not allow ROS2 services blocklist: diff --git a/docs/rst/notes/forthcoming_version.rst b/docs/rst/notes/forthcoming_version.rst index 8ecc0ed13..71f516cc4 100644 --- a/docs/rst/notes/forthcoming_version.rst +++ b/docs/rst/notes/forthcoming_version.rst @@ -8,17 +8,17 @@ Forthcoming Version This release includes the following **new features**: -* :ref:`XML Participant ` now supports topic-name endpoint profile lookup: - when creating a :term:`DataWriter` or :term:`DataReader` for a topic, a loaded XML profile whose name - matches the topic name is automatically applied, giving users full control over QoS fields such as - history, memory policy and transport. - A specific profile can also be selected per topic via the new ``endpoint-profile-name`` tag. - A new optional ``endpoint-qos-mode`` participant tag controls whether YAML QoS overrides the matching - XML profile (``xml-overridable``, default) or the profile is applied verbatim (``xml-standalone``). +* :ref:`XML Participant ` now supports endpoint profiles: + when creating a :term:`DataWriter` or :term:`DataReader` for a topic, a loaded XML ``data_writer`` or + ``data_reader`` profile whose name matches the topic name is automatically applied, giving users control over + QoS fields such as history, memory policy and transport. + A specific profile can also be selected via the new ``endpoint-profile-name`` Topic QoS tag. + ``durability``, ``reliability``, ``ownership`` and ``history-depth`` explicitly set in the YAML configuration + take precedence over the profile. For more details, see :ref:`user_manual_participants_xml_topic_profiles`. This release includes the following **documentation updates**: -* Document topic-name endpoint profile lookup for the :ref:`XML Participant `, +* Document endpoint profiles for the :ref:`XML Participant `, including QoS fields always enforced by the *DDS Router* regardless of the profile. -* Add *Endpoint Profiles* section to the :ref:`user_manual_configuration` page. +* Add *Endpoint profiles* section to the :ref:`user_manual_configuration` page. diff --git a/docs/rst/user_manual/configuration.rst b/docs/rst/user_manual/configuration.rst index b906e39bb..a1df5130c 100644 --- a/docs/rst/user_manual/configuration.rst +++ b/docs/rst/user_manual/configuration.rst @@ -85,7 +85,7 @@ Under the **optional** tag ``raw``, an XML configuration (with the same format a .. note:: - The |ddsrouter| does not modify any XML configuration in a :ref:`user_manual_participants_xml`. + The |ddsrouter| does not modify the DomainParticipant XML configuration of a :ref:`user_manual_participants_xml`. However, there are some QoS that can affect performance. These QoS should be configured by the user explicitly. Check :ref:`user_manual_participants_xml_profiles`. @@ -93,13 +93,10 @@ Under the **optional** tag ``raw``, an XML configuration (with the same format a Endpoint profiles ----------------- -Profiles named after a topic are automatically applied to :term:`DataWriter` and :term:`DataReader` endpoints -when they are created for that topic by an :ref:`XML Participant `. -A specific profile can also be selected per topic via the ``endpoint-profile-name`` tag, instead of relying -on the topic name. -By default, QoS fields explicitly set in the YAML configuration override the matching XML profile's values -(``endpoint-qos-mode: xml-overridable``); this can be changed to ``xml-standalone`` on the participant so the -XML profile is applied verbatim. +Loaded ``data_writer`` and ``data_reader`` profiles are also applied to the :term:`DataWriter` and :term:`DataReader` endpoints that an :ref:`XML Participant ` creates. +By default, the profile applied to an endpoint is the one whose name matches the topic name. +A different profile can be selected with the ``endpoint-profile-name`` tag of the :ref:`Topic QoS `. +When a profile is applied, only ``durability``, ``reliability``, ``ownership`` and ``history-depth`` override the values from the profile, and only if they are explicitly set in the YAML configuration. For more details, see :ref:`user_manual_participants_xml_topic_profiles`. Topics Configuration @@ -233,6 +230,12 @@ For more information on topics, please read the `Fast DDS Topic 1 + + DYNAMIC + + + DYNAMIC + # Relay topic rt/chatter and type std_msgs::msg::dds_::String_ @@ -1047,6 +1056,13 @@ A complete example of all the configurations described on this page can be found - Participant0 - Participant1 + - name: HelloWorldTopic + type: HelloWorld + qos: + endpoint-profile-name: "custom_endpoint_profile" + participants: + - xml_participant + # Do not allow ROS2 services blocklist: diff --git a/docs/rst/user_manual/participants/xml.rst b/docs/rst/user_manual/participants/xml.rst index 3b64eb47d..495ca2b23 100644 --- a/docs/rst/user_manual/participants/xml.rst +++ b/docs/rst/user_manual/participants/xml.rst @@ -76,68 +76,73 @@ Notice that not setting such QoS will not affect the correct functionality of th .. _user_manual_participants_xml_topic_profiles: -Topic-name endpoint profile lookup ------------------------------------ -When the XML Participant creates a DataWriter or DataReader for a topic, it looks for a loaded XML ``data_writer`` -or ``data_reader`` profile to configure that endpoint. +Endpoint profiles +----------------- + +When the XML Participant creates a :term:`DataWriter` or :term:`DataReader` for a topic, it looks for a loaded XML ``data_writer`` or ``data_reader`` profile to configure that endpoint. By default, the |ddsrouter| looks for a profile **whose name matches the topic name**. -If a matching profile is found, the endpoint is configured using that profile's QoS, giving the user -control over fields such as history, memory policy, transport, etc. -If no matching profile exists, the endpoint falls back to default QoS with values derived from the YAML configuration. +If a matching profile is found, the endpoint is configured using that profile's QoS, giving the user control over fields such as history, memory policy, transport, etc. +If no matching profile exists, the endpoint falls back to default QoS with values derived from the YAML configuration and from discovery. + +.. note:: + + Endpoint profiles are only applied by XML Participants. + The endpoints of any other Participant kind ignore them, even if a profile whose name matches the topic name is loaded. .. note:: Certain QoS are always enforced by the |ddsrouter| regardless of the XML profile: - deadline on DataWriters (set to minimum so it matches any reader), + ``deadline`` on DataWriters (set to the minimum value so it matches any DataReader), ``autodispose_unregistered_instances`` on DataWriters (set to ``false`` to preserve dispose/unregister forwarding semantics), and ``expects_inline_qos`` on DataReaders for keyed topics. -The following example loads a profile named ``my_topic`` that will be automatically applied when creating -endpoints for a topic of that name: +The following example loads a ``data_writer`` and a ``data_reader`` profile named ``my_topic`` that will be automatically applied when creating endpoints for a topic of that name: .. code-block:: xml - - - - DYNAMIC - - - DYNAMIC - - - + + + + DYNAMIC + + + DYNAMIC + + Selecting a profile explicitly -""""""""""""""""""""""""""""""" +"""""""""""""""""""""""""""""" -Instead of relying on the topic name, a specific profile can be selected for a topic with the -``endpoint-profile-name`` tag under that topic's QoS configuration. -When set, the |ddsrouter| looks up the XML profile with that name instead of the topic name: +Instead of relying on the topic name, a specific profile can be selected for a topic with the ``endpoint-profile-name`` tag of the :ref:`Topic QoS `. +When set, the |ddsrouter| looks up the ``data_writer`` and ``data_reader`` profiles with that name instead of the topic name: .. code-block:: yaml topics: - name: "rt/chatter" qos: - endpoint-profile-name: "my_reader_profile" + endpoint-profile-name: "chatter_profile" + participants: + - xml_participant + +As any other Topic QoS, ``endpoint-profile-name`` can be set in the :ref:`Manual Topics `, the :ref:`Participant Topic QoS ` and the :ref:`Specs Topic QoS `, with the same precedence among them. +Since XML profiles are loaded for the whole |ddsrouter| process, this is the way to apply different profiles to the same topic in different XML Participants. +If no profile with that name is loaded, the |ddsrouter| does not look for a profile named after the topic; the endpoint falls back to default QoS instead. Overriding profile QoS from the YAML configuration -""""""""""""""""""""""""""""""""""""""""""""""""""" +"""""""""""""""""""""""""""""""""""""""""""""""""" -When a matching XML profile is applied, the QoS fields explicitly set by the user in the YAML -configuration take precedence over the values in the XML profile. -This behavior is controlled by the ``endpoint-qos-mode`` participant tag, which accepts two values: +When a matching XML profile is applied, the following :ref:`Topic QoS ` override the corresponding values from the profile, but only if they are explicitly set in the YAML configuration (in the Manual Topics, the Participant Topic QoS or the Specs Topic QoS): +``durability``, ``reliability``, ``ownership`` and ``history-depth``. +Every other field keeps the value from the XML profile. -* ``xml-overridable`` *(default)*: the XML profile is applied first, and any QoS field explicitly set in - the YAML configuration overrides the corresponding value from the profile. -* ``xml-standalone``: the XML profile is applied verbatim; YAML QoS does not override it. +QoS values that the |ddsrouter| learns from remote endpoints during discovery never override the XML profile. +Fields that are set neither in the XML profile nor in the YAML configuration therefore take the |fastdds| default values (e.g. ``KEEP_LAST`` history with depth ``1``), instead of being adapted to the discovered endpoints. -.. code-block:: yaml +.. warning:: - - name: xml_participant - kind: xml - endpoint-qos-mode: xml-standalone + Setting ``history-depth`` in the Specs Topic QoS overrides the history of every matching XML profile, even when it is set to its default value of ``5000``. + Likewise, if the remote DataWriters use ``EXCLUSIVE_OWNERSHIP_QOS``, set ``ownership`` either in the XML profile or in the YAML configuration, otherwise the DataReaders of the XML Participant will not match them. Repeater diff --git a/resources/configurations/ddsrouter_config_schema.json b/resources/configurations/ddsrouter_config_schema.json index ad4d89559..62f119bae 100644 --- a/resources/configurations/ddsrouter_config_schema.json +++ b/resources/configurations/ddsrouter_config_schema.json @@ -160,6 +160,9 @@ "downsampling":{ "type":"integer", "minimum": 1 + }, + "endpoint-profile-name":{ + "type":"string" } }, "title": "QOS"