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 |
---|---|
|
Launches a server for Discovery Server. |
|
Allows manual cleaning of garbage files that may be generated by Shared Memory Transport |
|
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 |
---|---|
|
Produce help message with examples. |
|
IPv4/IPv6 address chosen to listen the clients using UDP transport. Defaults to any |
|
UDP port chosen to listen the clients. Defaults to ‘11811’. Only one server can be |
|
IPv4/IPv6 address chosen to listen the clients using TCP transport. Instead of an |
|
TCP port chosen to listen the clients. Defaults to ‘42100’. Only one server can be |
|
Creates a BACKUP server (see Discovery Protocol) |
|
XML configuration file (see XML profiles). In this case, the default |
|
Unique server identifier. Its functionality its deprecated. It can be used to select |
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
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
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
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
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
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
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
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
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
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
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 |
---|---|
|
Cleans SHM zombie files. |
Option |
Description |
---|---|
|
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 |
---|---|
|
Checks a xml profile by matching it against a XSD schema. |
Option |
Description |
---|---|
|
Produce help message. |
|
Print debug information (disabled by default) |
|
XSD schema for validation (not required, Fast DDS schema is used by default) |
Example
fastdds xml validate my_profile.xml