.. include:: ../../03-exports/aliases-api.include .. 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. .. contents:: :local: :backlinks: none :depth: 2 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 three verbs whose functionality is described in the following table: +--------------------------+-------------------------------------------------------------------------------------------+ | Verbs | Description | +==========================+===========================================================================================+ | ``discovery`` | Launches a server for :ref:`Discovery Server `. | +--------------------------+-------------------------------------------------------------------------------------------+ | ``shm`` | Allows manual cleaning of garbage files that may be generated by | | | :ref:`transport_sharedMemory_sharedMemory` | +--------------------------+-------------------------------------------------------------------------------------------+ | ``xml`` | Checks if a xml profile is well formed. | +--------------------------+-------------------------------------------------------------------------------------------+ .. _cli_discovery: discovery --------- This command launches a |SERVER| (or |BACKUP|) for :ref:`Discovery Server `. This *server* will manage the discovery phases of the |CLIENTS| which are connected to it. *Clients* must know how to reach the *server*, which is accomplished by specifying an IP address, the *servers* GUID prefix, and a transport protocol like UDP or TCP. *Servers* do not need any prior knowledge of their *clients*, but require a GUID prefix, and the listening IP address where they may be reached. For more information on the different *Fast DDS* discovery mechanisms and how to configure them, please refer to :ref:`discovery`. .. important:: It is possible to interconnect *servers* (or *backup* servers) instantiated with ``fastdds discovery`` using environment variable ``ROS_DISCOVERY_SERVER`` (see :ref:`env_vars_ros_discovery_server`) or a XML configuration file. .. _cli_discovery_run: How to run ^^^^^^^^^^ On a shell, execute: .. code-block:: bash fastdds discovery -i {0-255} [optional parameters] Where the parameters are: +--------------------------+-------------------------------------------------------------------------------------------+ | Option | Description | +==========================+===========================================================================================+ | ``-h -help`` | Produce help message. | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-i --server-id`` | Unique server identifier. Specifies zero based server position in |br| | | | ``ROS_DISCOVERY_SERVER`` environment variable. Must be an integer in range [0, 255] |br| | | | If not specified, it must be defined using a XML configuration file. | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-l --udp-address`` | IPv4/IPv6 address chosen to listen the clients using UDP transport. Defaults to any |br| | | | (0.0.0.0/::0). Instead of an address, a DNS domain name can be specified. | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-p --udp-port`` | UDP port chosen to listen the clients. Defaults to '11811'. | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-t --tcp-address`` | IPv4/IPv6 address chosen to listen the clients using TCP transport. Instead of an |br| | | | address, a DNS domain name can be specified. Defaults to localhost (127.0.0.1). | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-q --tcp-port`` | TCP port chosen to listen the clients. Defaults to '42100'. Only one server can be |br| | | | configured using the default port. | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-b --backup`` | Creates a BACKUP *server* (see :ref:`discovery_protocol`) | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-x --xml-file`` | XML configuration file (see :ref:`xml_profiles`). In this case, the default |br| | | | configuration file is not loaded. The CLI options override XML configuration for |br| | | | that specific parameter. The default profile in the XML file is loaded except if |br| | | | a specific profile name is specified: ``profile_name@xml_file`` | +--------------------------+-------------------------------------------------------------------------------------------+ The output is: .. code-block:: bash ### Server is running ### Participant Type: Security: Server ID: Server GUID prefix: 44.53..5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv4:[]: UDPv6:[]: TCPv4:[]:- TCPv6:[]:- Once the *server* is instantiated, the *clients* can be configured either programmatically or by XML (see :ref:`discovery_server`), or using environment variable ``ROS_DISCOVERY_SERVER`` (see :ref:`env_vars_ros_discovery_server`) .. note:: The :ref:`security` configuration of the discovery server should be done through XML. See example below. .. _cli_discovery_examples: 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 Output: .. code-block:: bash ### Server is running ### Participant Type: SERVER Security: NO Server ID: 0 Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv4:[0.0.0.0]:11811 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 Output: .. code-block:: bash ### Server is running ### Participant Type: SERVER Security: NO Server ID: 1 Server GUID prefix: 44.53.01.5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv4:[127.0.0.1]:14520 This same output can be obtained loading the following XML configuration file ``DiscoveryServerCLI.xml``: .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: XML-DS-CLI-XML-CONF<--> :end-before: <--> .. code-block:: bash fastdds discovery -x [PATH_TO_FILE]/DiscoveryServerCLI.xml 3. Launch a default server with id 1 (second on ``ROS_DISCOVERY_SERVER``) listening on IPv6 address ``2a02:ec80:600:ed1a::3`` with UDP port 14520. .. code-block:: bash fast-discovery-serverd-1.0.1.exe -i 1 -l 2a02:ec80:600:ed1a::3 -p 14520 Output: .. code-block:: bash ### Server is running ### Participant Type: SERVER Security: NO Server ID: 1 Server GUID prefix: 44.53.01.5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv6:[2a02:ec80:600:ed1a::3]:14520 4. Launch a default server with id 2 (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 2 -l 192.168.36.34 -p 8783 -l 172.20.96.1 -p 51083 Output: .. code-block:: bash ### Server is running ### Participant Type SERVER Security: NO Server ID: 2 Server GUID prefix: 44.53.02.5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv4:[192.168.36.34]:8783 UDPv4:[172.20.96.1]:51083 Using the same XML configuration file from the second example, the same output can be obtained loading a specific profile: `second_participant_profile_discovery_server_cli`. .. code-block:: bash fastdds discovery -x second_participant_profile_discovery_server_cli@[PATH_TO_FILE]/DiscoveryServerCLI.xml 5. Launch a default server with id 3 (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 3 -l 172.30.144.1 -p 12345 -b Output: .. code-block:: bash ### Server is running ### Participant Type BACKUP Security: NO Server ID: 3 Server GUID prefix: 44.53.03.5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv4:[172.30.144.1]:12345 6. Launch a default server with id 0 (first on ``ROS_DISCOVERY_SERVER``) listening on localhost with UDP port 14520. Only localhost clients can reach the server defining as `ROS_DISCOVERY_SERVER=localhost:14520`. .. code-block:: bash fastdds discovery -i 0 -l localhost -p 14520 Output: .. code-block:: bash ### Server is running ### Participant Type: SERVER Security: NO Server ID: 0 Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv4:[127.0.0.1]:14520 7. Launch a secure server with id 0 (first on ``ROS_DISCOVERY_SERVER``) listening on all available interfaces on UDP port '11811'. .. code-block:: bash fastdds discovery -x secure_discovery_server_cli@[PATH_TO_FILE]/DiscoveryServerCLI.xml Output: .. code-block:: bash ### Server is running ### Participant Type: SERVER Security: YES Server ID: 0 Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv4:[0.0.0.0]:11811 8. Launch a server with id 0 (first on ``ROS_DISCOVERY_SERVER``) reading specific `profile_name` configuration from XML file. .. code-block:: bash fastdds discovery -i 0 -x profile_name@[PATH_TO_FILE]/config.xml Output: .. code-block:: bash ### Server is running ### Participant Type: SERVER Security: NO Server ID: 0 Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 Server Addresses: UDPv4:[127.0.0.1]:56542 9. Launch a server with id 0 (first on ``ROS_DISCOVERY_SERVER``) listening on localhost on default TCP port '42100'. .. code-block:: bash fastdds discovery -i 0 -t 127.0.0.1 Output: .. code-block:: bash ### Server is running ### Participant Type: SERVER Security: NO Server ID: 0 Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 Server Addresses: TCPv4:[127.0.0.1]:42100-42100 10. Launch a server with id 0 (first on ``ROS_DISCOVERY_SERVER``) listening on localhost and WiFi (192.163.6.34). Two TCP ports need to be specified because TCP transports cannot share ports. .. code-block:: bash fastdds discovery -i 0 -t 127.0.0.1 -q 42100 -t 192.163.6.34 -q 42101 Output: .. code-block:: bash ### Server is running ### Participant Type: SERVER Security: NO Server ID: 0 Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41 Server Addresses: TCPv4:[127.0.0.1]:42100-42100 TCPv4:[192.163.6.34]:42101-42101 .. note:: When using Discovery Server over TCP, the first port shown in the output refers to the TCP Physical port and the second one to the TCP Logical port (see :ref:`transport_tcp_tcp`). .. note:: A server can be instantiated just by passing the port arguments ``-p`` and ``-q``. Fast DDS CLI will use the default values of the IP addresses, that is, ``0.0.0.0`` for UDP and ``127.0.0.1`` for TCP. .. _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. | +--------------------------+-------------------------------------------------------------------------------------------+ .. _cli_xml: xml --- Checks if a given xml profile is well formed, by matching it against a XSD schema. If the given input to the command is a path to a folder instead of a path to a file,all xml files contained in the folder will be validated. This validation consists in checking the lack of parameters, values bounds, expected values data types and main profile structure. For further information see :ref:`making_xml_profiles`. .. code-block:: bash fastdds xml [] +--------------------------+-------------------------------------------------------------------------------------------+ | Sub-command | Description | +==========================+===========================================================================================+ | ``validate`` | Checks a xml profile by matching it against a XSD schema. | +--------------------------+-------------------------------------------------------------------------------------------+ +--------------------------+-------------------------------------------------------------------------------------------+ | Option | Description | +==========================+===========================================================================================+ | ``-h --help`` | Produce help message. | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-d --debug`` | Print debug information (disabled by default) | +--------------------------+-------------------------------------------------------------------------------------------+ | ``-x --xsd_file`` | XSD schema for validation (not required, Fast DDS schema is used by default) | +--------------------------+-------------------------------------------------------------------------------------------+ **Example** .. code-block:: bash fastdds xml validate my_profile.xml