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

xml

Checks if a xml profile is well formed.

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, a port and a transport protocol like UDP or TCP. Servers do not need any prior knowledge of their clients, but require the listening IP address and port 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 [optional parameters]

Where the parameters are:

Option

Description

-h  --help

Produce help message with examples.

-l  --udp-address

IPv4/IPv6 address chosen to listen the clients using UDP transport. Defaults to any
(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’. Only one server can be
configured using the default UDP port.

-t  --tcp-address

IPv4/IPv6 address chosen to listen the clients using TCP transport. Instead of an
address, a DNS domain name can be specified. Defaults to any (0.0.0.0).

-q  --tcp-port

TCP port chosen to listen the clients. Defaults to ‘42100’. Only one server can be
configured using the default TCP port.

-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

-i  --server-id

Unique server identifier. Its functionality its deprecated. It can be used to select
a fixed GUID in the form shown below. Must be an integer in range [0, 255].

Executing the command without parameters will launch a server with default UDP values.

The output is:

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

Note

The Security configuration of the discovery server should be done through XML. See example below.

1.1.2. Examples

  1. Launch a default server listening on all available interfaces on UDP port ‘11811’. Only one server can use default values per machine.

    fastdds discovery
    

    Output:

    ### Server is running ###
      Participant Type:   SERVER
      Security:           NO
      Server GUID prefix: <Default GUID>
      Server Addresses:   UDPv4:[0.0.0.0]:11811
    
  2. Launch a default 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 -l 127.0.0.1 -p 14520
    

    Output:

    ### Server is running ###
      Participant Type:   SERVER
      Security:           NO
      Server GUID prefix: <Default GUID>
      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>
            <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>
            <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>
    
    <participant profile_name="secure_discovery_server_cli">
        <rtps>
            <builtin>
                <discovery_config>
                    <discoveryProtocol>SERVER</discoveryProtocol>
                </discovery_config>
                <metatrafficUnicastLocatorList>
                    <locator>
                        <udpv4>
                            <address>0.0.0.0</address>
                            <port>11811</port>
                        </udpv4>
                    </locator>
                </metatrafficUnicastLocatorList>
            </builtin>
            <propertiesPolicy>
                <properties>
                    <!-- Activate Auth:PKI-DH plugin -->
                    <property>
                        <name>dds.sec.auth.plugin</name>
                        <value>builtin.PKI-DH</value>
                    </property>
    
                    <!-- Configure Auth:PKI-DH plugin -->
                    <property>
                        <name>dds.sec.auth.builtin.PKI-DH.identity_ca</name>
                        <value>file://maincacert.pem</value>
                    </property>
                    <property>
                        <name>dds.sec.auth.builtin.PKI-DH.identity_certificate</name>
                        <value>file://appcert.pem</value>
                    </property>
                    <property>
                        <name>dds.sec.auth.builtin.PKI-DH.private_key</name>
                        <value>file://appkey.pem</value>
                    </property>
    
                    <!-- Activate Access:Permissions plugin -->
                    <property>
                        <name>dds.sec.access.plugin</name>
                        <value>builtin.Access-Permissions</value>
                    </property>
    
                    <!-- Configure Access:Permissions plugin -->
                    <property>
                        <name>dds.sec.access.builtin.Access-Permissions.permissions_ca</name>
                        <value>file://maincacet.pem</value>
                    </property>
                    <property>
                        <name>dds.sec.access.builtin.Access-Permissions.governance</name>
                        <value>file://governance.smime</value>
                    </property>
                    <property>
                        <name>dds.sec.access.builtin.Access-Permissions.permissions</name>
                        <value>file://permissions.smime</value>
                    </property>
    
                    <!-- Activate Crypto:AES-GCM-GMAC plugin -->
                    <property>
                        <name>dds.sec.crypto.plugin</name>
                        <value>builtin.AES-GCM-GMAC</value>
                    </property>
                </properties>
            </propertiesPolicy>
        </rtps>
    </participant>
    
    fastdds discovery -x [PATH_TO_FILE]/DiscoveryServerCLI.xml
    
  3. Launch a default server listening on all available interfaces on TCP port ‘42100’. Only one server can use default values per machine.

    fastdds discovery -t
    

    Output:

    ### Server is running ###
      Participant Type:   SERVER
      Security:           NO
      Server GUID prefix: <Default GUID>
      Server Addresses:   TCPv4:[0.0.0.0]:42100
    
  1. Launch a default server with GUID corresponding to id 1 (see Deprecated_CLI) listening on IPv6 address 2a02:ec80:600:ed1a::3 with UDP port 14520.

    fastdds discovery -i 1 -l 2a02:ec80:600:ed1a::3 -p 14520
    

    Output:

    ### Server is running ###
      Participant Type:   SERVER
      Security:           NO
      Server GUID prefix: 44.53.01.5f.45.50.52.4f.53.49.4d.41
      Server Addresses:   UDPv6:[2a02:ec80:600:ed1a::3]:14520
    
  2. Launch a default 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 -l 192.168.36.34 -p 8783 -l 172.20.96.1 -p 51083
    

    Output:

    ### Server is running ###
      Participant Type    SERVER
      Security:           NO
      Server GUID prefix: <Default GUID>
      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.

    fastdds discovery -x second_participant_profile_discovery_server_cli@[PATH_TO_FILE]/DiscoveryServerCLI.xml
    
  3. Launch a default 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 -l 172.30.144.1 -p 12345 -b
    

    Output:

    ### Server is running ###
      Participant Type    BACKUP
      Security:           NO
      Server GUID prefix: <Default GUID>
      Server Addresses:   UDPv4:[172.30.144.1]:12345
    
  4. Launch a secure 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 GUID prefix: <Default GUID>
      Server Addresses:   UDPv4:[0.0.0.0]:11811
    
  5. Launch a server reading specific profile_name configuration from XML file.

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

    Output:

    ### Server is running ###
      Participant Type:   SERVER
      Security:           NO
      Server GUID prefix: <Default GUID>
      Server Addresses:   UDPv4:[127.0.0.1]:56542
    
  6. Launch a server listening on localhost on default TCP port ‘42100’.

    fastdds discovery -t 127.0.0.1
    

    Output:

    ### Server is running ###
      Participant Type:   SERVER
      Security:           NO
      Server GUID prefix: <Default GUID>
      Server Addresses:   TCPv4:[127.0.0.1]:42100-42100
    
  7. Launch a server listening on localhost and WiFi (192.163.6.34). Two TCP ports need to be specified because transports cannot share ports.

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

    Output:

    ### Server is running ###
      Participant Type:   SERVER
      Security:           NO
      Server GUID prefix: <Default GUID>
      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 TCP Transport).

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 0.0.0.0 for TCP.

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.

1.3. 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 Creating an XML profiles file.

fastdds xml [<xml-command>]

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

fastdds xml validate my_profile.xml