Skip to content

Commit

Permalink
Added new section for CLI tool and updated environment variable [8974] (
Browse files Browse the repository at this point in the history 
#184)

* Refs #8974: Updated ROS2_AUTO_CLIENT_SERVER to ROS_DISCOVERY_SERVER

Signed-off-by: imontesino <monte.igna@gmail.com>

* Refs #8974: added section for CLI tools discovery and shm

Signed-off-by: imontesino <monte.igna@gmail.com>

* Refs #8974: Added localhost, wifi and shm to spelling

Signed-off-by: imontesino <monte.igna@gmail.com>

* Refs #8974: Applied suggested changes

Signed-off-by: imontesino <monte.igna@gmail.com>

* Refs #8974: Fixed trailing whitespace

Signed-off-by: imontesino <monte.igna@gmail.com>

* Refs #8974: Fixed inline literal issue

Signed-off-by: imontesino <monte.igna@gmail.com>

* Refs #8974: Applied suggested changes

Signed-off-by: imontesino <monte.igna@gmail.com>

* Refs #8974: Applied suggested changes

Signed-off-by: imontesino <monte.igna@gmail.com>

* Refs #8974: Applied suggested changes

Signed-off-by: imontesino <monte.igna@gmail.com>
  • Loading branch information
@imontesino
imontesino authored Aug 3, 2020
1 parent c4069a5 commit 8cfb268
Show file tree
Hide file tree
Showing 4 changed files with 195 additions and 32 deletions.
77 changes: 45 additions & 32 deletions docs/fastdds/env_vars/env_vars.rst
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. include:: ../../03-exports/aliases-api.include

.. _env_vars:

Environment variables
Expand All @@ -13,45 +15,56 @@ This is the list of environment variables that affect the behavior of *Fast DDS*
+------------------------------------------------------------------+
| **Linux** |
+------------------------------------------------------------------+
| .. code-block:: |
| .. code-block:: bash |
| |
| export FASTRTPS_DEFAULT_PROFILES_FILE=/home/user/profiles.xml |
+------------------------------------------------------------------+
| **Windows** |
+------------------------------------------------------------------+
| .. code-block:: |
| .. code-block:: bash |
| |
| set FASTRTPS_DEFAULT_PROFILES_FILE=C:\profiles.xml |
+------------------------------------------------------------------+


``ROS2_AUTO_CLIENT_SERVER``
When this variable is set, it automatically activates the :ref:`Server-Client Discovery<discovery_server>`.
The value of the variable must represent the locator of the server,
in the form of the IP address (e.g., '192.168.2.23') or address-port pair (e.g., '192.168.2.23:24353').
If no port is specified, the default port 11311 is used.

If the specified address is a local address of the current machine, it will start the
:ref:`dds_layer_domainParticipant` as a server.
If the address is a remote one, or if there is already a server at the given port,
it will start the DomainParticipant as a client,
connecting to the server at the specified locator.

+--------------------------------------------------------------+
| **Linux** |
+--------------------------------------------------------------+
| .. code-block:: |
| |
| export ROS2_AUTO_CLIENT_SERVER=192.168.2.23:24353 |
+--------------------------------------------------------------+
| **Windows** |
+--------------------------------------------------------------+
| .. code-block:: |
| |
| set ROS2_AUTO_CLIENT_SERVER=192.168.2.23:24353 |
+--------------------------------------------------------------+


``FASTDDS_AUTO_CLIENT_SERVER``
An alias for ``ROS2_AUTO_CLIENT_SERVER``.
If both variables are defined, only the value of ``ROS2_AUTO_CLIENT_SERVER`` is used.
``ROS_DISCOVERY_SERVER``
When setting this variable the :ref:`DomainParticipant<dds_layer_domainParticipant>` is configured as a Client of
the given Server, implementing the :ref:`Server-Client Discovery<discovery_server>` mechanism, provided its
:ref:`dds_layer_domainParticipant`'s |discoveryProtocol| setting has been left configured as default
(:ref:`Simple discovery<simple_disc_settings>`).
The value of the variable must list the locator of the server
in the form of the IP address (e.g., '192.168.2.23') or IP-port pair (e.g., '192.168.2.23:24353').
If no port is specified, the default port 11811 is used. For more information on how to configure the discovery
mechanism in *Fast DDS*, please refer to :ref:`discovery`.

.. warning::
The environment variable is only used in the case where :ref:`discoveryProtocol<discovery_protocol>`
is set to |SIMPLE|.
In any other case the environment variable has no effect.

To set more than one address they must be separated by semicolons.
The server's Id is determined by their position in the list.
A blank space between semicolons means the corresponding Id is free.


**Example**

The following example shows how to set the address of two remote discovery servers with addresses
'84.22.259.329:8888' and '81.41.17.102:1234' and Ids 0 and 2 respectively.

+----------------------------------------------------------------------------+
| **Linux** |
+----------------------------------------------------------------------------+
| .. code-block:: bash |
| |
| export ROS_DISCOVERY_SERVER=84.22.259.329:8888;;81.41.17.102:1234 |
+----------------------------------------------------------------------------+
| **Windows** |
+----------------------------------------------------------------------------+
| .. code-block:: bash |
| |
| set ROS_DISCOVERY_SERVER=84.22.259.329:8888;;81.41.17.102:1234 |
+----------------------------------------------------------------------------+



137 changes: 137 additions & 0 deletions docs/fastddscli/cli/cli.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
.. include:: ../../03-exports/roles.include

.. _ffastddscli_cli:

CLI
===

The *Fast DDS* command line interface provides a set commands and sub-commands to perform, *Fast DDS*
related, maintenance and configuration tasks.

An executable file for Linux and Windows that runs the *Fast DDS CLI* application is
available in the `tools` folder.
If the `tools/fastdds` folder path is added to the ``PATH``, or by sourcing the `<path/to/fastdds>/install/setup.bash`
configuration file, *Fast DDS CLI* can be executed running the following commands:

- Linux:

.. code-block:: bash
$ fastdds <command> [<command-args>]
- Windows:

.. code-block:: bash
> fastdds.bat <command> [<command-args>]
There are two verbs whose functionality is described in the following table:

+--------------------------+-------------------------------------------------------------------------------------------+
| Verbs | Description |
+==========================+===========================================================================================+
| ``discovery`` | Launches a server for :ref:`Server-Client Discovery<discovery_server>`. |
+--------------------------+-------------------------------------------------------------------------------------------+
| ``shm`` | Allows manual cleaning of garbage files that may be generated by |
| | :ref:`transport_sharedMemory_sharedMemory` |
+--------------------------+-------------------------------------------------------------------------------------------+

.. _cli_discovery:

discovery
---------

Launches a server for :ref:`Server-Client Discovery<discovery_server>`. This server will manage the messages of the
clients which are pointed to its IP address.
Clients must be aware of how to reach the server by specifying an IP address and a transport protocol like UDP
or TCP.
Servers do not need any knowledge of their clients beforehand, but require the listening IP address, where they
may be reached.
For more information on how to configure the discovery mechanism in *Fast DDS*, please refer to :ref:`discovery`.

.. code-block:: bash
fastdds discovery -i {0-255} [optional parameters]
Where the parameters are:

+--------------------------+-------------------------------------------------------------------------------------------+
| Option | Description |
+==========================+===========================================================================================+
| ``-i --server-id`` | **Mandatory** unique server identifier. Specifies zero based server position in |br| |
| | ``ROS_DISCOVERY_SERVER`` environment variable. |
+--------------------------+-------------------------------------------------------------------------------------------+
| ``-h -help`` | Produce help message. |
+--------------------------+-------------------------------------------------------------------------------------------+
| ``-l --ip-address`` | IP address chosen to listen the clients. Defaults to any (0.0.0.0). |
+--------------------------+-------------------------------------------------------------------------------------------+
| ``-p --port`` | UDP port chosen to listen the clients. Defaults to '11811'. |
+--------------------------+-------------------------------------------------------------------------------------------+
| ``-b --backup`` | Creates a server with a backup file associated. |
+--------------------------+-------------------------------------------------------------------------------------------+

Examples
^^^^^^^^

1. Launch a default server with id 0 (first on ``ROS_DISCOVERY_SERVER``)
listening on all available interfaces on UDP port '11811'. Only one
server can use default values per machine.

.. code-block:: bash
fastdds discovery -i 0
2. Launch a default server with id 1 (second on ``ROS_DISCOVERY_SERVER``)
listening on localhost with UDP port 14520. Only localhost clients
can reach the server defining as `ROS_DISCOVERY_SERVER=;127.0.0.1:14520` .

.. code-block:: bash
fastdds discovery -i 1 -l 127.0.0.1 -p 14520
3. Launch a default server with id 3 (third on ``ROS_DISCOVERY_SERVER``)
listening on WiFi (192.168.36.34) and Ethernet (172.20.96.1) local
interfaces with UDP ports 8783 and 51083 respectively
(addresses and ports are made up for the example).

.. code-block:: bash
fastdds discovery -i 1 -l 192.168.36.34 -p 14520 -l 172.20.96.1 -p 51083
4. Launch a default server with id 4 (fourth on ``ROS_DISCOVERY_SERVER``)
listening on 172.30.144.1 with UDP port 12345 and provided with a
backup file. If the server crashes it will automatically restore its
previous state when re-enacted.


.. code-block:: bash
fastdds discovery -i 1 -l 172.30.144.1 -p 12345 -b
.. _cli_shm:

shm
---

Provides maintenance tasks related with :ref:`transport_sharedMemory_sharedMemory`. Shared Memory transport creates
:ref:`Segments<transport_sharedMemory_concepts_segment>`, blocks of memory accessible from different processes.
Zombie files are memory blocks that were reserved by shared memory and are no longer in use which take up valuable
memory resources.
This tool finds and frees those memory allocations.

.. code-block:: bash
fastdds shm [<shm-command>]
+--------------------------+-------------------------------------------------------------------------------------------+
| Sub-command | Description |
+==========================+===========================================================================================+
| ``clean`` | Cleans SHM zombie files. |
+--------------------------+-------------------------------------------------------------------------------------------+

+--------------------------+-------------------------------------------------------------------------------------------+
| Option | Description |
+==========================+===========================================================================================+
| ``-h -help`` | Produce help message. |
+--------------------------+-------------------------------------------------------------------------------------------+
10 changes: 10 additions & 0 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,16 @@
/fastddsgen/pubsub_app/pubsub_app
/fastddsgen/dataTypes/dataTypes

.. _index_cli:

.. toctree::
:caption: Fast DDS CLI
:maxdepth: 2
:numbered: 5
:hidden:

/fastddscli/cli/cli

.. _index_notes:

.. toctree::
Expand Down
3 changes: 3 additions & 0 deletions docs/spelling_wordlist.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ IPv
kB
libs
lifecycle
localhost
LogTopic
loopback
lroundl
Expand Down Expand Up @@ -139,6 +140,7 @@ simpleEDP
seqNum
SequenceNumber
sequencenumbers
shm
sqlite
stateful
struct
Expand Down Expand Up @@ -169,6 +171,7 @@ vcstool
wget
whitelist
whitelists
WiFi
Wireshark
worskspace
WString
Expand Down

0 comments on commit 8cfb268

Please sign in to comment.