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) or a XML configuration file.

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`	Unique server identifier. Specifies zero based server position in `ROS_DISCOVERY_SERVER` environment variable. Must be an integer in range [0, 255] If not specified, it must be defined using a XML configuration file.
`-h -help`	Produce help message.
`-l --ip-address`	IPv4 address chosen to listen the clients. Defaults to any (0.0.0.0). Instead of an address, a name can be specified (see Configure Discovery Server locators using names)
`-p --port`	UDP port chosen to listen the clients. Defaults to ‘11811’.
`-b --backup`	Creates a BACKUP server (see Discovery Protocol)
`-x --xml-file`	XML configuration file (see XML profiles). In this case, the default configuration file is not loaded. The CLI options override XML configuration for that specific parameter. The default profile in the XML file is loaded except if a specific profile name is specified: `profile_name@xml_file`

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¶

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

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

This same output can be obtained loading the following XML configuration file DiscoveryServerCLI.xml:

<participant profile_name="participant_profile_discovery_server_cli" is_default_profile="true">
    <rtps>
        <prefix>44.53.01.5f.45.50.52.4f.53.49.4d.41</prefix>
        <builtin>
            <discovery_config>
                <discoveryProtocol>SERVER</discoveryProtocol>
            </discovery_config>
            <metatrafficUnicastLocatorList>
                <locator>
                    <udpv4>
                        <address>localhost</address>
                        <port>14520</port>
                    </udpv4>
                </locator>
            </metatrafficUnicastLocatorList>
        </builtin>
    </rtps>
</participant>

<participant profile_name="second_participant_profile_discovery_server_cli">
    <rtps>
        <prefix>44.53.02.5f.45.50.52.4f.53.49.4d.41</prefix>
        <builtin>
            <discovery_config>
                <discoveryProtocol>SERVER</discoveryProtocol>
            </discovery_config>
            <metatrafficUnicastLocatorList>
                <locator>
                    <udpv4>
                        <address>192.168.36.34</address>
                        <port>8783</port>
                    </udpv4>
                </locator>
                <locator>
                    <udpv4>
                        <address>172.20.96.1</address>
                        <port>51083</port>
                    </udpv4>
                </locator>
            </metatrafficUnicastLocatorList>
        </builtin>
    </rtps>
</participant>

fastdds discovery -x [PATH_TO_FILE]/DiscoveryServerCLI.xml

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

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

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

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