Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[22616] Easy Mode enhancement and tutorial docs #233

Merged
merged 7 commits into from
Jan 23, 2025
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Refs #22616: Auto Discovery Server Mode tutorial
Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>
Mario-DL committed Jan 17, 2025
commit dd623443365801e4a9c89d50df27c1ecbd24a618
Original file line number Diff line number Diff line change
@@ -21,3 +21,4 @@ For tutorials related to cloud or cloud-edge deployments, please refer :ref:`tut
user_topics_multicast/user_topics_multicast
keys/topic_keys
keys/filtered_topic_keys
easy_mode/easy_mode
81 changes: 81 additions & 0 deletions docs/rst/tutorials/core/deployment/easy_mode/easy_mode.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
.. include:: ../../../../exports/alias.include

.. _easy_mode_tutorial:

Easy Mode Tutorial
==================

This tutorial aims to demonstrate the use

.. contents::
:depth: 2
:local:
:backlinks: none

Prerequisites
-------------

* It is recommended to have a basic understanding of ``Vulcanexus Easy Mode`` introduced in the :ref:`easy_mode` section.
* An up-to-date (latest) Vulcanexus installation using one of the following installation methods:

* :ref:`linux_binary_installation`
* :ref:`linux_source_installation`
* :ref:`docker_installation`

Preparation
-----------

Lets start by setting up the Vulcanexus environment.
For this, there are two possible options:

#. Running the Vulcanexus Docker image (recommended).

Run the Vulcanexus Docker image with:

.. code-block:: bash

docker run -it --rm ubuntu-vulcanexus:{DISTRO}-desktop

Then, within the container, source the Vulcanexus installation with:

.. code-block:: bash

source /opt/vulcanexus/{DISTRO}/setup.bash

Repeat these steps in a second terminal.

#. Running the tutorial on the local host (note that more than one host connected to the same network will be needed).
For this second option, it is necessary to have the ``vucanexus-jazzy-base`` package installed.

In both hosts, source the following file to setup the Vulcanexus environment:

.. code-block:: bash

source /opt/vulcanexus/{DISTRO}/setup.bash

Running the demo
----------------

The demo will be exemplified using Docker.
It consists in two docker containers (hosts) running a ROS 2 talker - listener example with the new ``Vulcanexus Easy Mode`` enabled.
Both hosts are in the same network and domain id as shown in the following diagram:

.. image:: ../../../../figures/enhancements/easy_mode/easy_mode_tutorial.png
:align: center
:width: 55%

Discovery server in Host A will serve as the master server.
Hence, the IP address of Host A will be used to enable the ``Easy Mode`` in both containers.
Run the following commands in each container:

.. code-block:: bash

# Container 1
EASY_MODE=172.17.0.2 ros2 run demo_nodes_cpp talker

# Container 2
EASY_MODE=172.17.0.2 ros2 run demo_nodes_cpp listener

After a moment, the listener should start receiving samples from the talker, meaning that both Discovery Servers are now connected to each other.
As the talker and listener nodes share the same topic ``chatter``, nodes are discovered and data exchange can happen.
Further benefits of using the new ``Easy Mode`` are detailed in the :ref:`easy_mode_benefits` section.