1. 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 Discovery Server.

shm

Allows manual cleaning of garbage files that may be generated by Shared Memory Transport

1.1. discovery

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

Important

It is possible to interconnect servers (or backup servers) instantiated with fastdds discovery using environment variable ROS_DISCOVERY_SERVER (see ROS_DISCOVERY_SERVER).

1.1.1. How to run

On a shell, execute:

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
ROS_DISCOVERY_SERVER environment variable. Must be an integer in range [0, 255]

-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 BACKUP server (see Discovery Protocol)

The output is:

### Server is running ###
  Participant Type:   <SERVER|BACKUP>
  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>
                      UDPv4:[<ip-address>]:<port>

Once the server is instantiated, the clients can be configured either programmatically or by XML (see Discovery Server Settings), or using environment variable ROS_DISCOVERY_SERVER (see ROS_DISCOVERY_SERVER)

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

1.2. shm

Provides maintenance tasks related with Shared Memory Transport. Shared Memory transport creates 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.

fastdds shm [<shm-command>]

Sub-command

Description

clean

Cleans SHM zombie files.

Option

Description

-h  -help

Produce help message.