From 8cfb268a3f0f99f76a016ff3974fbb8bbb349e37 Mon Sep 17 00:00:00 2001 From: imontesino Date: Mon, 3 Aug 2020 11:25:39 +0200 Subject: [PATCH] Added new section for CLI tool and updated environment variable [8974] (#184) * Refs #8974: Updated ROS2_AUTO_CLIENT_SERVER to ROS_DISCOVERY_SERVER Signed-off-by: imontesino * Refs #8974: added section for CLI tools discovery and shm Signed-off-by: imontesino * Refs #8974: Added localhost, wifi and shm to spelling Signed-off-by: imontesino * Refs #8974: Applied suggested changes Signed-off-by: imontesino * Refs #8974: Fixed trailing whitespace Signed-off-by: imontesino * Refs #8974: Fixed inline literal issue Signed-off-by: imontesino * Refs #8974: Applied suggested changes Signed-off-by: imontesino * Refs #8974: Applied suggested changes Signed-off-by: imontesino * Refs #8974: Applied suggested changes Signed-off-by: imontesino --- docs/fastdds/env_vars/env_vars.rst | 77 +++++++++------- docs/fastddscli/cli/cli.rst | 137 +++++++++++++++++++++++++++++ docs/index.rst | 10 +++ docs/spelling_wordlist.txt | 3 + 4 files changed, 195 insertions(+), 32 deletions(-) create mode 100644 docs/fastddscli/cli/cli.rst diff --git a/docs/fastdds/env_vars/env_vars.rst b/docs/fastdds/env_vars/env_vars.rst index 248cf6f1e..4132550bc 100644 --- a/docs/fastdds/env_vars/env_vars.rst +++ b/docs/fastdds/env_vars/env_vars.rst @@ -1,3 +1,5 @@ +.. include:: ../../03-exports/aliases-api.include + .. _env_vars: Environment variables @@ -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`. - 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` is configured as a Client of + the given Server, implementing the :ref:`Server-Client Discovery` mechanism, provided its + :ref:`dds_layer_domainParticipant`'s |discoveryProtocol| setting has been left configured as default + (:ref:`Simple discovery`). + 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` + 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 | + +----------------------------------------------------------------------------+ + + + diff --git a/docs/fastddscli/cli/cli.rst b/docs/fastddscli/cli/cli.rst new file mode 100644 index 000000000..82e018268 --- /dev/null +++ b/docs/fastddscli/cli/cli.rst @@ -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 `/install/setup.bash` +configuration file, *Fast DDS CLI* can be executed running the following commands: + +- Linux: + + .. code-block:: bash + + $ fastdds [] + +- Windows: + + .. code-block:: bash + + > fastdds.bat [] + +There are two verbs whose functionality is described in the following table: + ++--------------------------+-------------------------------------------------------------------------------------------+ +| Verbs | Description | ++==========================+===========================================================================================+ +| ``discovery`` | Launches a server for :ref:`Server-Client Discovery`. | ++--------------------------+-------------------------------------------------------------------------------------------+ +| ``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`. 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`, 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 [] + ++--------------------------+-------------------------------------------------------------------------------------------+ +| Sub-command | Description | ++==========================+===========================================================================================+ +| ``clean`` | Cleans SHM zombie files. | ++--------------------------+-------------------------------------------------------------------------------------------+ + ++--------------------------+-------------------------------------------------------------------------------------------+ +| Option | Description | ++==========================+===========================================================================================+ +| ``-h -help`` | Produce help message. | ++--------------------------+-------------------------------------------------------------------------------------------+ diff --git a/docs/index.rst b/docs/index.rst index a02a23a35..397b87e13 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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:: diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 541097f7a..40c94e100 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -89,6 +89,7 @@ IPv kB libs lifecycle +localhost LogTopic loopback lroundl @@ -139,6 +140,7 @@ simpleEDP seqNum SequenceNumber sequencenumbers +shm sqlite stateful struct @@ -169,6 +171,7 @@ vcstool wget whitelist whitelists +WiFi Wireshark worskspace WString