Skip to content

Latest commit

 

History

History
349 lines (249 loc) · 14.7 KB

cli.rst

File metadata and controls

349 lines (249 loc) · 14.7 KB
Raw

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:

    $ fastdds <command> [<command-args>]

  • Windows:

    > 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:`Discovery Server <discovery_server>`.
shm Allows manual cleaning of garbage files that may be generated by :ref:`transport_sharedMemory_sharedMemory`

discovery

This command launches a |SERVER| (or |BACKUP|) for :ref:`Discovery Server <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.

How to run

On a shell, execute:

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:

### Server is running ###
  Participant Type:   <SERVER|BACKUP>
  Security:           <YES|NO>
  Server ID:          <server-id>
  Server GUID prefix: 44.53.<server-id-in-hex>.5f.45.50.52.4f.53.49.4d.41
  Server Addresses:   UDPv4:[<ip-address>]:<port>
                      TCPv4:[<ip-address>]:<physical-port>-<logical-port>

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.

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.

    fastdds discovery -i 0

    Output:

    ### 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 .

    fastdds discovery -i 1 -l 127.0.0.1 -p 14520

    Output:

    ### 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: <!--><-->


    fastdds discovery -x [PATH_TO_FILE]/DiscoveryServerCLI.xml

  3. 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).

    fastdds discovery -i 2 -l 192.168.36.34 -p 8783 -l 172.20.96.1 -p 51083

    Output:

    ### 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 of the previous example, the same output can be obtained loading a specific

    fastdds discovery -x second_participant_profile_discovery_server_cli@[PATH_TO_FILE]/DiscoveryServerCLI.xml

  4. 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.

    fastdds discovery -i 3 -l 172.30.144.1 -p 12345 -b

    Output:

    ### 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

  5. 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.

    fastdds discovery -i 0 -l localhost -p 14520

    Output:

    ### 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

  1. Launch a secure server with id 0 (first on ROS_DISCOVERY_SERVER) listening on all available interfaces on UDP port '11811'.

    fastdds discovery -x secure_discovery_server_cli@[PATH_TO_FILE]/DiscoveryServerCLI.xml

    Output:

    ### 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

  2. Launch a server with id 0 (first on ROS_DISCOVERY_SERVER) reading specific profile_name configuration from XML file.

    fastdds discovery -i 0 -x profile_name@[PATH_TO_FILE]/config.xml

    Output:

    ### 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

  3. Launch a server with id 0 (first on ROS_DISCOVERY_SERVER) listening on localhost on default TCP port '42100'.

    fastdds discovery -i 0 -t 127.0.0.1

    Output:

    ### 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

  4. 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.

    fastdds discovery -i 0 -t 127.0.0.1 -q 42100 -t 192.163.6.34 -q 42101

    Output:

    ### 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.

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.

fastdds shm [<shm-command>]
Sub-command Description
clean Cleans SHM zombie files.
Option Description
-h -help Produce help message.